endia 0.0.0-stage → 0.0.2

package/dist/archives/docker-ignore.js

@@ -0,0 +1,250 @@
+/**
+ * Docker's name for an ignore file. A recipe may have its own ignore file beside it, named as the recipe's file name followed by
+ * this name, such as `recipes/dotnet.Dockerfile.dockerignore`.
+ */
+export const IgnoreFileName = ".dockerignore";
+/** EastIndia's name for an ignore file, which a build reads in preference to a `.dockerignore` in the same place. */
+export const EndiaIgnoreFileName = ".endiaignore";
+/** The first character of a comment line. */
+const CommentMarker = "#";
+/** The first character of a pattern that re-includes what earlier patterns excluded. */
+const ReincludeMarker = "!";
+/** A leading byte-order mark, which the file may start with and which is not part of its first line. */
+const ByteOrderMark = "";
+/**
+ * A build context's ignore file: which of the context's files a build leaves out of the archive it sends, so that no `COPY` can copy
+ * them and they do not change the build key. It matches paths by the same rules as the `endia` CLI, which follows Docker's
+ * `.dockerignore` matching. A folder sent by this client therefore gives the same archive as the same folder sent by the CLI.
+ *
+ * Patterns are cleaned and anchored at the context root, and a leading `/` is dropped. `*` and `?` stop at `/`, `**` spans folders,
+ * and `[...]` is a character class. A later line overrides an earlier one, and `!` re-includes. A path is ignored when the pattern
+ * that decides it matches the path itself or any of its parent folders.
+ */
+export class DockerIgnore {
+    patterns;
+    constructor(patterns) {
+        this.patterns = patterns;
+    }
+    /** An ignore file that excludes nothing, for a context without one. */
+    static empty = new DockerIgnore([]);
+    /**
+     * Reads the text of an ignore file. Lines end in LF or CRLF. Blank lines and lines whose first non-blank character is `#` are
+     * skipped.
+     *
+     * @param text - The file's content.
+     * @param file - The file's path, which error messages name.
+     * @returns The ignore file.
+     * @throws Error naming the file, the line and the column of every malformed pattern.
+     */
+    static parse(text, file = IgnoreFileName) {
+        const patterns = [];
+        const problems = [];
+        const lines = (text.startsWith(ByteOrderMark) ? text.slice(1) : text).split("\n").map((line) => line.replace(/\r$/u, ""));
+        lines.forEach((raw, index) => {
+            const trimmed = raw.trim();
+            if (trimmed.length === 0 || trimmed.startsWith(CommentMarker)) {
+                return;
+            }
+            const at = `${file}:${String(index + 1)}:${String(raw.length - raw.trimStart().length + 1)}`;
+            const reincludes = trimmed.startsWith(ReincludeMarker);
+            const body = reincludes ? trimmed.slice(1).trim() : trimmed;
+            if (body.length === 0) {
+                problems.push(`${at}: A '${ReincludeMarker}' needs a pattern after it.`);
+                return;
+            }
+            // Patterns are anchored at the context root, so a leading '/' says nothing more.
+            let cleaned = cleanPath(body);
+            if (cleaned.length > 1 && cleaned.startsWith("/")) {
+                cleaned = cleaned.slice(1);
+            }
+            const compiled = compilePattern(cleaned);
+            if (typeof compiled === "string") {
+                problems.push(`${at}: The pattern '${trimmed}' is not valid: ${compiled}.`);
+            }
+            else {
+                patterns.push({ expression: compiled, reincludes });
+            }
+        });
+        if (problems.length > 0) {
+            throw new Error(problems.join("\n"));
+        }
+        return new DockerIgnore(patterns);
+    }
+    /**
+     * Whether any line re-includes with `!`. Only then can a path under a left-out folder be sent, so only then must a walk of the
+     * context look inside a left-out folder.
+     */
+    get reincludes() {
+        return this.patterns.some((pattern) => pattern.reincludes);
+    }
+    /**
+     * Decides whether a context path is left out. The patterns apply in file order, and the last pattern that matches decides. The
+     * context root itself is never left out.
+     *
+     * @param path - A path relative to the context root, with `/` separators.
+     * @returns True when the path, or one of its parent folders, is left out.
+     * @throws Error when the path leads outside the context.
+     */
+    isIgnored(path) {
+        const cleaned = cleanPath(path).replace(/^\/+/u, "");
+        if (cleaned === ".." || cleaned.startsWith("../")) {
+            throw new Error(`The path '${path}' points outside the build context.`);
+        }
+        if (cleaned.length === 0 || cleaned === ".") {
+            return false;
+        }
+        const parents = [];
+        for (let slash = cleaned.indexOf("/"); slash >= 0; slash = cleaned.indexOf("/", slash + 1)) {
+            parents.push(cleaned.slice(0, slash));
+        }
+        let ignored = false;
+        for (const pattern of this.patterns) {
+            // A re-including pattern can only undo a match, and an excluding one can only add one, so a pattern that could change nothing is skipped.
+            if (pattern.reincludes !== ignored) {
+                continue;
+            }
+            if (pattern.expression.test(cleaned) || parents.some((parent) => pattern.expression.test(parent))) {
+                ignored = !pattern.reincludes;
+            }
+        }
+        return ignored;
+    }
+}
+/**
+ * Cleans a path with `/` separators by the rules of Go's `path.Clean`, which Docker applies to ignore patterns.
+ *
+ * - Empty and `.` segments are dropped.
+ * - A `..` removes the segment before it; at the start of a relative path it stays.
+ * - An empty result is `.`.
+ *
+ * @param path - The path.
+ * @returns The cleaned path.
+ */
+export function cleanPath(path) {
+    if (path.length === 0) {
+        return ".";
+    }
+    const rooted = path.startsWith("/");
+    const segments = [];
+    for (const segment of path.split("/")) {
+        if (segment.length === 0 || segment === ".") {
+            continue;
+        }
+        if (segment === "..") {
+            if (segments.length > 0 && segments[segments.length - 1] !== "..") {
+                segments.pop();
+            }
+            else if (!rooted) {
+                segments.push("..");
+            }
+            continue;
+        }
+        segments.push(segment);
+    }
+    const joined = segments.join("/");
+    return rooted ? `/${joined}` : joined.length === 0 ? "." : joined;
+}
+/**
+ * Translates a cleaned pattern into a regular expression over a whole context path. `*` becomes any characters other than `/`, `?`
+ * becomes one such character, `**` spans folders, `[...]` is a character class, and a backslash escapes the next character.
+ *
+ * @returns The expression, or the reason the pattern is not valid.
+ */
+function compilePattern(pattern) {
+    let text = "^";
+    for (let index = 0; index < pattern.length;) {
+        const character = pattern.charAt(index);
+        if (character === "*") {
+            const star = translateStar(pattern, index);
+            text += star.text;
+            index = star.next;
+        }
+        else if (character === "?") {
+            text += "[^/]";
+            index++;
+        }
+        else if (character === "[") {
+            const characterClass = translateClass(pattern, index);
+            if (characterClass === undefined) {
+                return "a '[' has no closing ']'";
+            }
+            text += characterClass.text;
+            index = characterClass.next;
+        }
+        else if (character === "\\") {
+            if (index + 1 >= pattern.length) {
+                return "a trailing '\\' escapes nothing";
+            }
+            text += escapeCharacter(pattern.charAt(index + 1));
+            index += 2;
+        }
+        else {
+            text += escapeCharacter(character);
+            index++;
+        }
+    }
+    return new RegExp(`${text}$`, "su");
+}
+/**
+ * Translates the `*` or `**` at an index. A single `*` matches any characters other than `/`. A `**` consumes a `/` that follows it;
+ * at the end of the pattern it matches anything, and elsewhere any number of whole folders, including none, so `logs/**` does not
+ * match `logs` itself.
+ */
+function translateStar(pattern, index) {
+    if (pattern.charAt(index + 1) !== "*") {
+        return { text: "[^/]*", next: index + 1 };
+    }
+    let next = index + 2;
+    if (pattern.charAt(next) === "/") {
+        next++;
+    }
+    return { text: next >= pattern.length ? ".*" : "(?:.*/)?", next };
+}
+/**
+ * Translates the `[...]` class at an index. In a class, `^` first negates, a backslash escapes, `a-z` is a range, and a `]` first in
+ * the class is a literal.
+ *
+ * @returns The translation and the index after the class, or undefined when the class has no closing `]`.
+ */
+function translateClass(pattern, index) {
+    let position = index + 1;
+    let text = "[";
+    if (pattern.charAt(position) === "^") {
+        text += "^";
+        position++;
+    }
+    let members = 0;
+    while (position < pattern.length && (pattern.charAt(position) !== "]" || members === 0)) {
+        let character = pattern.charAt(position);
+        if (character === "\\") {
+            position++;
+            if (position >= pattern.length) {
+                break;
+            }
+            character = pattern.charAt(position);
+            text += /[a-zA-Z0-9]/u.test(character) ? character : escapeClassCharacter(character);
+        }
+        else if (character === "-" && members > 0 && position + 1 < pattern.length && pattern.charAt(position + 1) !== "]") {
+            text += "-";
+        }
+        else {
+            text += escapeClassCharacter(character);
+        }
+        members++;
+        position++;
+    }
+    return position >= pattern.length ? undefined : { text: `${text}]`, next: position + 1 };
+}
+/**
+ * The characters a regular expression gives a meaning of its own outside a class. A regular expression in Unicode mode refuses an
+ * escape of any other character, so only these are escaped.
+ */
+const SyntaxCharacters = /[\\^$.*+?()[\]{}|/]/u;
+/** The characters with a meaning of their own inside a class: the syntax characters and `-`, which writes a range. */
+const ClassSyntaxCharacters = /[\\^$.*+?()[\]{}|/-]/u;
+function escapeCharacter(character) {
+    return SyntaxCharacters.test(character) ? `\\${character}` : character;
+}
+function escapeClassCharacter(character) {
+    return ClassSyntaxCharacters.test(character) ? `\\${character}` : character;
+}

package/dist/archives/fleet-archive.d.ts

@@ -0,0 +1,33 @@
+import { ArchiveFile } from "./archive-file.js";
+import type { ComposeModel } from "../contract/compose.js";
+import type { PurposeBody } from "../purposes.js";
+/**
+ * Writes the body of `compose up`, as the `endia` CLI writes it: one tar archive holding what the service needs from the caller's
+ * side, because a caller in a sandbox shares no folder with the host.
+ *
+ * - `compose.json` is the resolved model.
+ * - `contexts/<service>/` holds the build context of each selected service that has `build`, with the files a build would send.
+ * - `binds/<service>/<index>` holds the source of each bind mount of every service, by the index of its entry in the service's
+ *   `volumes`, counted from 0: a folder with everything under it, or a file.
+ * - `purpose.json` is the purpose's title and detail, present only when the caller sets the fleet's purpose as it comes up; the
+ *   service stores it before any other work.
+ *
+ * @param model - The resolved model.
+ * @param modelText - The model's JSON text, sent as `compose.json` exactly as the caller gave it.
+ * @param services - The services named for `compose up`; none selects every service. The selection adds the services they depend on.
+ * @param purpose - The fleet's purpose to set as it comes up, as `purposeBody` gives it; undefined leaves the fleet's purpose as it is.
+ * @returns The archive; the caller deletes it.
+ * @throws Error when a built service's context is not a folder or its recipe lies outside it, or when a bind mount's source does not
+ * exist. Nothing is sent then.
+ */
+export declare function packFleet(model: ComposeModel, modelText: string, services: readonly string[], purpose?: PurposeBody): Promise<ArchiveFile>;
+/**
+ * Gives the selected services: those named with every service they depend on, directly or through another, or every service when
+ * none is named.
+ *
+ * @param model - The resolved model.
+ * @param named - The services named.
+ * @returns The selected services' names.
+ * @throws Error when a named service is not in the model.
+ */
+export declare function selectServices(model: ComposeModel, named: readonly string[]): ReadonlySet<string>;

package/dist/archives/fleet-archive.js

@@ -0,0 +1,134 @@
+import { existsSync, statSync } from "node:fs";
+import { readdir, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import { ArchiveFile } from "./archive-file.js";
+import { contextEntries, defaultRecipe, ignoreFileFor, pathInside } from "./build-context.js";
+/** The name of the resolved model in the archive. */
+const ModelEntry = "compose.json";
+/** The name of the purpose the caller sets as the fleet comes up, in the archive. */
+const PurposeEntry = "purpose.json";
+/** The folder of the archive that holds each built service's context, as `contexts/<service>/`. */
+const ContextsFolder = "contexts";
+/** The folder of the archive that holds each bind mount's source, as `binds/<service>/<index of the volume entry>`. */
+const BindsFolder = "binds";
+/** The type of a volume entry whose source is a file or folder on the caller's side. */
+const BindType = "bind";
+/**
+ * Writes the body of `compose up`, as the `endia` CLI writes it: one tar archive holding what the service needs from the caller's
+ * side, because a caller in a sandbox shares no folder with the host.
+ *
+ * - `compose.json` is the resolved model.
+ * - `contexts/<service>/` holds the build context of each selected service that has `build`, with the files a build would send.
+ * - `binds/<service>/<index>` holds the source of each bind mount of every service, by the index of its entry in the service's
+ *   `volumes`, counted from 0: a folder with everything under it, or a file.
+ * - `purpose.json` is the purpose's title and detail, present only when the caller sets the fleet's purpose as it comes up; the
+ *   service stores it before any other work.
+ *
+ * @param model - The resolved model.
+ * @param modelText - The model's JSON text, sent as `compose.json` exactly as the caller gave it.
+ * @param services - The services named for `compose up`; none selects every service. The selection adds the services they depend on.
+ * @param purpose - The fleet's purpose to set as it comes up, as `purposeBody` gives it; undefined leaves the fleet's purpose as it is.
+ * @returns The archive; the caller deletes it.
+ * @throws Error when a built service's context is not a folder or its recipe lies outside it, or when a bind mount's source does not
+ * exist. Nothing is sent then.
+ */
+export async function packFleet(model, modelText, services, purpose) {
+    const selected = selectServices(model, services);
+    const entries = [];
+    for (const [name, service] of Object.entries(model.services)) {
+        if (service.build && selected.has(name)) {
+            entries.push(...await builtContextEntries(name, service.build));
+        }
+        for (const [index, volume] of (service.volumes ?? []).entries()) {
+            if (volume.type === BindType && volume.source !== undefined) {
+                entries.push(...await bindEntries(name, index, volume.source));
+            }
+        }
+    }
+    const texts = [{ name: ModelEntry, text: modelText }];
+    if (purpose !== undefined) {
+        texts.push({ name: PurposeEntry, text: JSON.stringify(purpose) });
+    }
+    return ArchiveFile.write(entries, texts, true);
+}
+/**
+ * Gives the selected services: those named with every service they depend on, directly or through another, or every service when
+ * none is named.
+ *
+ * @param model - The resolved model.
+ * @param named - The services named.
+ * @returns The selected services' names.
+ * @throws Error when a named service is not in the model.
+ */
+export function selectServices(model, named) {
+    if (named.length === 0) {
+        return new Set(Object.keys(model.services));
+    }
+    const selected = new Set();
+    const pending = [...named];
+    for (let name = pending.pop(); name !== undefined; name = pending.pop()) {
+        const service = model.services[name];
+        if (service === undefined) {
+            throw new Error(`The Compose model has no service "${name}".`);
+        }
+        if (!selected.has(name)) {
+            selected.add(name);
+            pending.push(...dependenciesOf(service));
+        }
+    }
+    return selected;
+}
+function dependenciesOf(service) {
+    const dependsOn = service.depends_on ?? [];
+    return Array.isArray(dependsOn) ? [...dependsOn] : Object.keys(dependsOn);
+}
+// A context's files are named under contexts/<service>/; its folders are not sent, only the root's own entry. The service accepts
+// only files and folders in this archive, so a link in the context is sent as what it points at: a link to a file as that file,
+// and a link to a folder as an empty folder.
+async function builtContextEntries(service, build) {
+    const context = build.context;
+    if (context === undefined) {
+        throw new Error(`Service "${service}" has a build without a context.`);
+    }
+    if (!existsSync(context) || !statSync(context).isDirectory()) {
+        throw new Error(`The build context '${context}' of service "${service}" is not a folder.`);
+    }
+    const recipe = path.resolve(context, build.dockerfile ?? defaultRecipe(path.resolve(context)));
+    const inside = pathInside(context, recipe);
+    if (inside === undefined) {
+        throw new Error(`The recipe '${recipe}' of service "${service}" must be inside its build context '${context}'.`);
+    }
+    const root = `${ContextsFolder}/${service}/`;
+    const files = (await contextEntries(path.resolve(context), inside, ignoreFileFor(path.resolve(context), recipe))).filter((entry) => !entry.name.endsWith("/"));
+    return [{ source: context, name: root }, ...files.map((entry) => ({ source: entry.source, name: root + entry.name }))];
+}
+async function bindEntries(service, index, source) {
+    const root = `${BindsFolder}/${service}/${String(index)}`;
+    const item = await stat(source).catch(() => undefined);
+    if (item === undefined) {
+        throw new Error(`The bind mount source '${source}' of service "${service}" does not exist.`);
+    }
+    if (!item.isDirectory()) {
+        return [{ source, name: root }];
+    }
+    const entries = [{ source, name: `${root}/` }];
+    await collectEverything(source, `${root}/`, entries, new Set([await realpath(source)]));
+    return entries;
+}
+// Every folder and file under a folder, each folder before what it holds. A link is followed to what it points at, because the
+// service accepts only files and folders in this archive; a link back to a folder already being walked is refused.
+async function collectEverything(folder, prefix, entries, walking) {
+    for (const name of (await readdir(folder)).sort()) {
+        const source = path.join(folder, name);
+        if (!(await stat(source)).isDirectory()) {
+            entries.push({ source, name: prefix + name });
+            continue;
+        }
+        const real = await realpath(source);
+        if (walking.has(real)) {
+            throw new Error(`The folder '${source}' leads back to a folder that holds it.`);
+        }
+        entries.push({ source, name: `${prefix}${name}/` });
+        await collectEverything(source, `${prefix}${name}/`, entries, new Set([...walking, real]));
+    }
+}

package/dist/compose-model.d.ts

@@ -0,0 +1,32 @@
+import type { ComposeModel } from "./contract/compose.js";
+/** Which Compose project to resolve, as the options of `endia compose` choose it. */
+export interface ComposeProjectOptions {
+    /** The Compose files, in order; when undefined, the CLI finds them as `docker compose` does, from the working folder. */
+    readonly files?: readonly string[];
+    /** The Compose project's name; the service names the fleet after it. */
+    readonly projectName?: string;
+    /** The folder against which relative paths are resolved; the first file's folder when undefined. */
+    readonly projectDirectory?: string;
+    /** Files of variables whose values the CLI fills into the Compose files; `.env` in the project folder when undefined. */
+    readonly envFiles?: readonly string[];
+    /** The working folder of the CLI. When `files` is undefined, the CLI looks for Compose files in this folder and its parents. */
+    readonly cwd?: string;
+    /** The `endia` program; `endia` on the `PATH` when undefined. */
+    readonly cli?: string;
+}
+/** The resolved model, both as the object the client reads and as the exact JSON text the CLI printed. */
+export interface ResolvedComposeModel {
+    readonly model: ComposeModel;
+    readonly text: string;
+}
+/**
+ * Resolves a Compose project with the `endia` CLI, for `FleetsClient.up` to send. The client does not read Compose files itself.
+ * The CLI reads the files, merges them, fills in their variables and checks them by the rules the service applies. It then prints
+ * the resolved model, with every path absolute, as `endia compose config --format json`. A caller without the CLI can write the
+ * resolved model itself.
+ *
+ * @param options - The files, the project name and folder, and the variable files.
+ * @returns The resolved model.
+ * @throws Error with the CLI's own message when the project is not valid or the CLI cannot be run.
+ */
+export declare function resolveComposeModel(options?: ComposeProjectOptions): Promise<ResolvedComposeModel>;

package/dist/compose-model.js

@@ -0,0 +1,39 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const run = promisify(execFile);
+/** The most output read from the CLI, far more than any resolved model needs; Node's default of 1 MiB could cut a large model short. */
+const MaxModelBytes = 64 * 1024 * 1024;
+/**
+ * Resolves a Compose project with the `endia` CLI, for `FleetsClient.up` to send. The client does not read Compose files itself.
+ * The CLI reads the files, merges them, fills in their variables and checks them by the rules the service applies. It then prints
+ * the resolved model, with every path absolute, as `endia compose config --format json`. A caller without the CLI can write the
+ * resolved model itself.
+ *
+ * @param options - The files, the project name and folder, and the variable files.
+ * @returns The resolved model.
+ * @throws Error with the CLI's own message when the project is not valid or the CLI cannot be run.
+ */
+export async function resolveComposeModel(options = {}) {
+    const args = ["compose"];
+    for (const file of options.files ?? []) {
+        args.push("--file", file);
+    }
+    if (options.projectName !== undefined) {
+        args.push("--project-name", options.projectName);
+    }
+    if (options.projectDirectory !== undefined) {
+        args.push("--project-directory", options.projectDirectory);
+    }
+    for (const file of options.envFiles ?? []) {
+        args.push("--env-file", file);
+    }
+    args.push("config", "--format", "json");
+    try {
+        const { stdout } = await run(options.cli ?? "endia", args, { cwd: options.cwd, maxBuffer: MaxModelBytes, encoding: "utf8" });
+        return { model: JSON.parse(stdout), text: stdout };
+    }
+    catch (error) {
+        const stderr = typeof error === "object" && error !== null && "stderr" in error ? String(error.stderr).trim() : "";
+        throw new Error(`endia compose config failed${stderr === "" ? "" : `: ${stderr}`}`, { cause: error });
+    }
+}

package/dist/contract/archives.d.ts

@@ -0,0 +1,14 @@
+import type { Timestamp } from "./common.js";
+/** What a path in a machine is, as the archive routes describe it in their `X-EastIndia-Path-Stat` header, Docker's `X-Docker-Container-Path-Stat`: its name, size, kind, time of last change and, for a link, what it points at. `endia cp` decides where a copy lands from it. */
+export interface PathStat {
+    /** The path's last name. */
+    readonly name: string;
+    /** A file's size in bytes; 0 for a folder or a link. */
+    readonly size: number;
+    /** What the path is: `file`, `directory` or `link`. */
+    readonly mode: string;
+    /** When the path last changed. */
+    readonly mtime: Timestamp;
+    /** What a link points at, as the link holds it; null for a file or a folder. */
+    readonly linkTarget: string | null;
+}

package/dist/contract/archives.js

@@ -0,0 +1 @@
+export {};

package/dist/contract/bases.d.ts

@@ -0,0 +1,48 @@
+/** The JSON body of `POST /v1/bases/import`, which `endia import` sends. The import makes a Windows disk that is already on the host into an image with no parent. The request names the disk, the reference the image will carry, whether to move or copy the disk into the image folder, and the recipe instructions that set the image's configuration, as `docker import --change` does. */
+export interface BaseImportRequest {
+    /** The full path of the disk on the host, for example `M:/eastindia/win11-desktop.vhdx`. */
+    readonly path: string;
+    /** The name and optional tag that the image will carry, for example `lab/windows-desktop:approved`; without a tag, `latest`. */
+    readonly reference: string;
+    /** Whether to move the disk into the image folder; when false, the disk is copied there. */
+    readonly move?: boolean;
+    /** The recipe instructions applied to the image's configuration, in order, each one line such as `ENV LANG=en-GB`. Only `LABEL`, `ENV`, `WORKDIR`, `CMD`, `ENTRYPOINT` and `EXPOSE` are accepted. */
+    readonly changes?: readonly string[];
+}
+/** The JSON body of `POST /v1/bases/prepare`, which `endia base prepare` sends: install Windows from an installation disc on the host, with EastIndia's guest programs and SSH, and import the result as a base. The password reaches only the answer file inside the new Windows and the service's memory; the service writes it nowhere else. */
+export interface BasePrepareRequest {
+    /** The full path on the host of the Windows installation disc, an ISO file, for example `M:/eastindia/windows11.iso`. */
+    readonly iso: string;
+    /** The tag that the base will carry, for example `lab/windows-desktop:approved`. */
+    readonly tag: string;
+    /** The number of the Windows edition on the disc, counted from 1 as Windows Setup counts them. */
+    readonly imageIndex?: number;
+    /** The standard account that Windows signs in automatically at every start. */
+    readonly desktopUser?: string;
+    /** The administrator account whose name and password answer an elevation prompt. */
+    readonly adminUser?: string;
+    /** The password of both accounts. */
+    readonly password: string;
+}
+/** The result of a finished import: the digest and reference of the new image, the path of its disk, how the disk came into the image folder, and what the import check found when the import started a virtual machine from the disk. */
+export interface BaseImportResult {
+    /** The image's digest, which is the SHA-256 of its disk; `endia import` prints it. */
+    readonly digest: string;
+    /** The reference that names the image, in the form `name:tag`. */
+    readonly reference: string;
+    /** The full path of the disk in the image folder. */
+    readonly diskPath: string;
+    /** How the disk came into the image folder: `inPlace` when it was already there and is used where it is, `copied` when a copy was made and the original left where it was, or `moved` when the original was renamed into the folder, or copied and then deleted. */
+    readonly broughtIn: string;
+    /** The checks of the import check, in the order they ran. A finished import passed every one. */
+    readonly checks: readonly BaseCheckReport[];
+}
+/** The outcome of one check that an import makes on a virtual machine it starts from the imported disk. Together these checks are the import check. */
+export interface BaseCheckReport {
+    /** The fixed name of the check: `guest-service`, `fast-startup`, `desktop`, `ssh`, `evaluation` or `shutdown`. */
+    readonly name: string;
+    /** Whether the check passed. */
+    readonly passed: boolean;
+    /** What the check saw, as text, such as the banner that the SSH server sent. */
+    readonly detail: string;
+}

package/dist/contract/bases.js

@@ -0,0 +1 @@
+export {};

package/dist/contract/clients.d.ts

@@ -0,0 +1,29 @@
+import type { Timestamp } from "./common.js";
+/** One issued client certificate as `GET /v1/clients` lists it and `DELETE /v1/clients/{name}` answers it: the record in `clients.json`, without any key. */
+export interface ClientCertificateSummary {
+    /** The certificate's name, its common name. */
+    readonly name: string;
+    /** `valid`, `expired` or `revoked`. */
+    readonly state: string;
+    /** The certificate's serial number, in hexadecimal. */
+    readonly serialNumber: string;
+    /** When the certificate was issued. */
+    readonly issued: Timestamp;
+    /** When the certificate stops being valid. */
+    readonly expires: Timestamp;
+    /** When the certificate was revoked, or null. */
+    readonly revoked: Timestamp | null;
+}
+/** The answer of `POST /v1/clients`: the three files a caller over HTTPS holds, as PEM text. The service keeps the certificate's record in `clients.json` and does not keep the private key. */
+export interface IssuedClientCertificate {
+    /** The certificate's name, its common name. */
+    readonly name: string;
+    /** When the certificate stops being valid. */
+    readonly expires: Timestamp;
+    /** `ca.pem`: the authority that signed the service's server certificate. */
+    readonly authority: string;
+    /** `cert.pem`: the client certificate. */
+    readonly certificate: string;
+    /** `key.pem`: the client certificate's private key, unencrypted PKCS#8. */
+    readonly key: string;
+}

package/dist/contract/clients.js

@@ -0,0 +1 @@
+export {};

package/dist/contract/common.d.ts

@@ -0,0 +1,30 @@
+/**
+ * A time as the API writes it: RFC 3339 in UTC with seven fractional digits, such as `2026-10-05T14:03:22.1234567Z`.
+ *
+ * Times stay strings because a JavaScript `Date` keeps only milliseconds, and the API identifies a process by its exact start time:
+ * a `started` value read from one answer is sent back unchanged in later requests.
+ */
+export type Timestamp = string;
+/** The JSON form of one refusal or one failed operation. */
+export interface ApiError {
+    /** One of the API's error codes, such as `NOT_FOUND`, `TIMEOUT` or `BUILD_FAILED`. */
+    readonly code: string;
+    /** What was expected and what was found, in one or two sentences. */
+    readonly message: string;
+    /** The field at fault: a request member, a Compose path or a recipe position; null when no one field is at fault. */
+    readonly fieldPath?: string | null;
+    /** The code's own data, such as `candidates` for an ambiguous prefix; null when the code carries none. */
+    readonly details?: Readonly<Record<string, unknown>> | null;
+}
+/** A rectangle on the screen or in a window, in pixels. */
+export interface WindowBounds {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * The filters of a list route, as `endia ps -f` and the other list commands take them: each key with every value given for it,
+ * such as `{ label: ["team=qa"], status: ["running"] }`.
+ */
+export type Filters = Readonly<Record<string, readonly string[]>>;

package/dist/contract/common.js

@@ -0,0 +1 @@
+export {};

package/dist/contract/compose.d.ts

@@ -0,0 +1,27 @@
+/**
+ * A resolved Compose model, as `endia compose config --format json` prints it: long syntax, every path absolute, and the project
+ * name set. The service checks the whole model; this client reads only the parts that name files on the caller's side.
+ */
+export interface ComposeModel {
+    /** The project name, which is the fleet's name. */
+    readonly name: string;
+    /** The services by name. */
+    readonly services: Readonly<Record<string, ComposeService>>;
+    readonly [member: string]: unknown;
+}
+/** The parts of one service of a resolved Compose model that name files on the caller's side. */
+export interface ComposeService {
+    readonly build?: {
+        readonly context?: string;
+        readonly dockerfile?: string;
+        readonly [member: string]: unknown;
+    } | null;
+    readonly volumes?: readonly {
+        readonly type?: string;
+        readonly source?: string;
+        readonly [member: string]: unknown;
+    }[] | null;
+    /** The services this one depends on: a map by service name in the resolved model, or a list of names. */
+    readonly depends_on?: Readonly<Record<string, unknown>> | readonly string[] | null;
+    readonly [member: string]: unknown;
+}

package/dist/contract/compose.js

@@ -0,0 +1 @@
+export {};