endia 0.0.0-stage → 0.0.2

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,35 @@
-# Temporary Holding Version
+# endia
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Client for EastIndia, which runs Windows desktop test machines that tests drive like Docker containers. Early preview: the product is not released yet.
+
+The package needs Node 20 or later and ships ES modules with TypeScript declarations. It calls the EastIndia service's HTTPS API, so a Node test runner can build images, bring fleets of machines up and down, and run programs in them without the `endia` command line.
+
+## Example
+
+`ledger/Endiafile` holds a recipe of two stages; each stage begins with a `FROM`, and `AS` names it:
+
+```dockerfile
+FROM eastindia/development:latest AS tools
+RUN choco install -y git
+
+FROM tools AS app
+COPY publish/ C:/app/
+```
+
+```js
+import { EastIndiaClient } from "endia";
+
+// Connects where the endia command line would: EASTINDIA_HOST and EASTINDIA_CERT_PATH, or its current context.
+const client = EastIndiaClient.fromEnv();
+console.log((await client.version()).version);
+
+const build = await client.images.build({ folder: "./ledger" }, { tags: ["lab/ledger:1"] });
+const built = await build.result({ onLog: (text) => process.stdout.write(text) });
+console.log(built.digest);
+
+// A recipe of several stages: target names the stage to build, here the first.
+const tools = await (await client.images.build({ folder: "./ledger" }, { target: "tools", tags: ["lab/tools:1"] })).result();
+console.log(tools.stages?.map((stage) => [stage.name, stage.cacheHit]));
+
+client.close();
+```

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

@@ -0,0 +1,36 @@
+import type { RequestBody } from "../transport/api-connection.js";
+/** One entry of an archive: the file, folder or link on disk, and the name the entry takes in the archive. */
+export interface ArchiveEntry {
+    /** The full path on disk. A link is archived as a link, never as what it points at. */
+    readonly source: string;
+    /** The name in the archive, with `/` separators; a folder's name ends in `/`. */
+    readonly name: string;
+}
+/**
+ * A tar archive written to a temporary file, so that a request that is sent again after a failed connection sends the same bytes.
+ * The archive belongs to the caller that wrote it, which deletes it with `delete` once the request has been answered.
+ */
+export declare class ArchiveFile {
+    private readonly folder;
+    /** The archive's full path. */
+    readonly path: string;
+    /** The archive's size in bytes. */
+    readonly size: number;
+    private constructor();
+    /**
+     * Writes an archive of the given entries, in the given order, in the POSIX pax format with UTF-8 names.
+     *
+     * @param entries - The entries. A folder entry holds only itself; each file under it needs its own entry.
+     * @param texts - Files that exist only in memory, such as a resolved Compose model, each written under its name.
+     * @param followLinks - Whether a link is written as what it points at, rather than as a link.
+     * @returns The archive.
+     */
+    static write(entries: readonly ArchiveEntry[], texts?: readonly {
+        name: string;
+        text: string;
+    }[], followLinks?: boolean): Promise<ArchiveFile>;
+    /** The archive as a request body, opened afresh for each attempt. */
+    get body(): RequestBody;
+    /** Deletes the archive and its temporary folder. */
+    delete(): Promise<void>;
+}

package/dist/archives/archive-file.js

@@ -0,0 +1,71 @@
+import { createReadStream } from "node:fs";
+import { mkdtemp, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { create } from "tar";
+import { MediaTypes } from "../routes.js";
+/** The prefix of the temporary folder that holds an archive while it is sent. */
+const TemporaryFolderPrefix = "eastindia-client-";
+/** The file name of the archive inside its temporary folder. */
+const ArchiveFileName = "archive.tar";
+/**
+ * A tar archive written to a temporary file, so that a request that is sent again after a failed connection sends the same bytes.
+ * The archive belongs to the caller that wrote it, which deletes it with `delete` once the request has been answered.
+ */
+export class ArchiveFile {
+    folder;
+    /** The archive's full path. */
+    path;
+    /** The archive's size in bytes. */
+    size;
+    constructor(folder, size) {
+        this.folder = folder;
+        this.path = path.join(folder, ArchiveFileName);
+        this.size = size;
+    }
+    /**
+     * Writes an archive of the given entries, in the given order, in the POSIX pax format with UTF-8 names.
+     *
+     * @param entries - The entries. A folder entry holds only itself; each file under it needs its own entry.
+     * @param texts - Files that exist only in memory, such as a resolved Compose model, each written under its name.
+     * @param followLinks - Whether a link is written as what it points at, rather than as a link.
+     * @returns The archive.
+     */
+    static async write(entries, texts = [], followLinks = false) {
+        const folder = await mkdtemp(path.join(tmpdir(), TemporaryFolderPrefix));
+        try {
+            // The texts are written beside the archive and added like any other file, under their own names.
+            const written = await Promise.all(texts.map(async (entry, index) => {
+                const source = path.join(folder, `text-${String(index)}`);
+                await writeFile(source, entry.text, "utf8");
+                return { source, name: entry.name };
+            }));
+            const all = [...written, ...entries];
+            const names = new Map(all.map((entry) => [path.resolve(entry.source), entry.name]));
+            await create({
+                file: path.join(folder, ArchiveFileName),
+                preservePaths: true,
+                noDirRecurse: true,
+                follow: followLinks,
+                // Each entry is read from its full path and renamed to its name in the archive.
+                onWriteEntry: (entry) => {
+                    entry.path = names.get(entry.absolute) ?? entry.path;
+                },
+            }, all.map((entry) => entry.source));
+            const size = (await stat(path.join(folder, ArchiveFileName))).size;
+            return new ArchiveFile(folder, size);
+        }
+        catch (error) {
+            await rm(folder, { recursive: true, force: true });
+            throw error;
+        }
+    }
+    /** The archive as a request body, opened afresh for each attempt. */
+    get body() {
+        return { contentType: MediaTypes.tar, open: () => createReadStream(this.path), length: this.size };
+    }
+    /** Deletes the archive and its temporary folder. */
+    async delete() {
+        await rm(this.folder, { recursive: true, force: true });
+    }
+}

package/dist/archives/build-context.d.ts

@@ -0,0 +1,63 @@
+import { ArchiveFile, type ArchiveEntry } from "./archive-file.js";
+/** The archive of a build context, and the recipe's path inside it, which the build request names as `dockerfile`. */
+export interface PackedContext {
+    readonly archive: ArchiveFile;
+    readonly recipe: string;
+}
+/**
+ * Packs a build context folder as `endia build` sends it: a tar archive of every file, folder and link in the folder that the
+ * ignore file does not exclude. A link is archived as a link, never as what it points at. The recipe and the ignore file are always
+ * sent.
+ *
+ * The ignore file is chosen as `ignoreFileFor` chooses it. A recipe outside the folder is added at the archive's root as
+ * `.dockerfile.` followed by 16 random hexadecimal digits, as Docker adds it, with its own ignore file beside it under that name
+ * followed by `.endiaignore` or `.dockerignore`, as the file on disk is named.
+ *
+ * @param folder - The context folder.
+ * @param recipe - The recipe's path, inside the folder or outside it; when undefined, `Endiafile` in the folder when it exists,
+ * and `Dockerfile` otherwise.
+ * @returns The archive and the recipe's path inside it; the caller deletes the archive.
+ * @throws Error when the folder does not exist, when a recipe outside the folder does not exist, or when the ignore file holds a
+ * malformed pattern.
+ */
+export declare function packBuildContext(folder: string, recipe?: string): Promise<PackedContext>;
+/**
+ * Lists the entries of a context folder that a build sends, each folder followed by what it holds, in ordinal order of name within
+ * each folder. `compose up` sends each service's build context with the same entries.
+ *
+ * @param root - The context folder's full path.
+ * @param recipe - The recipe's path inside the folder, with `/` separators, or undefined when it lies outside.
+ * @param ignoreFile - The ignore file's full path, which may not exist.
+ * @returns Each entry's full path and its path inside the folder; a folder's path ends in `/`.
+ */
+export declare function contextEntries(root: string, recipe: string | undefined, ignoreFile: string): Promise<ArchiveEntry[]>;
+/**
+ * Gives the recipe of a build that names none, as the `endia` CLI chooses it: `Endiafile` at the root of the context folder when it
+ * exists, and `Dockerfile` otherwise.
+ *
+ * @param root - The context folder's full path.
+ * @returns The recipe's file name.
+ */
+export declare function defaultRecipe(root: string): string;
+/**
+ * Gives the ignore file that applies to a recipe, as the `endia` CLI chooses it: the first of these that exists. A recipe's own
+ * ignore file is named as the recipe's file name followed by the ignore file's name, beside the recipe.
+ *
+ * 1. The recipe's own `.endiaignore`.
+ * 2. The recipe's own `.dockerignore`.
+ * 3. `.endiaignore` at the root of the folder.
+ * 4. `.dockerignore` at the root of the folder.
+ *
+ * @param root - The context folder's full path.
+ * @param recipe - The recipe's full path.
+ * @returns The ignore file's full path; `.dockerignore` at the root, which does not exist, when none of the four exists.
+ */
+export declare function ignoreFileFor(root: string, recipe: string): string;
+/**
+ * Gives a path's place inside a folder.
+ *
+ * @param root - The folder's full path.
+ * @param target - A full path.
+ * @returns The path inside the folder with `/` separators, or undefined when it lies outside the folder.
+ */
+export declare function pathInside(root: string, target: string): string | undefined;

package/dist/archives/build-context.js

@@ -0,0 +1,132 @@
+import { randomBytes } from "node:crypto";
+import { existsSync, statSync } from "node:fs";
+import { lstat, readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { ArchiveFile } from "./archive-file.js";
+import { DockerIgnore, EndiaIgnoreFileName, IgnoreFileName } from "./docker-ignore.js";
+/** EastIndia's name for a recipe, which a build that names none reads first. */
+const Endiafile = "Endiafile";
+/** Docker's name for a recipe, which a build that names none reads when the context holds no `Endiafile`. */
+const Dockerfile = "Dockerfile";
+/** The name prefix of a recipe that lies outside the context folder, which Docker adds at the archive's root under a random name. */
+const OutsideRecipePrefix = ".dockerfile.";
+/** The number of random bytes in that name; each byte gives two hexadecimal digits, so the name ends in 16 digits. */
+const OutsideRecipeRandomBytes = 8;
+/**
+ * Packs a build context folder as `endia build` sends it: a tar archive of every file, folder and link in the folder that the
+ * ignore file does not exclude. A link is archived as a link, never as what it points at. The recipe and the ignore file are always
+ * sent.
+ *
+ * The ignore file is chosen as `ignoreFileFor` chooses it. A recipe outside the folder is added at the archive's root as
+ * `.dockerfile.` followed by 16 random hexadecimal digits, as Docker adds it, with its own ignore file beside it under that name
+ * followed by `.endiaignore` or `.dockerignore`, as the file on disk is named.
+ *
+ * @param folder - The context folder.
+ * @param recipe - The recipe's path, inside the folder or outside it; when undefined, `Endiafile` in the folder when it exists,
+ * and `Dockerfile` otherwise.
+ * @returns The archive and the recipe's path inside it; the caller deletes the archive.
+ * @throws Error when the folder does not exist, when a recipe outside the folder does not exist, or when the ignore file holds a
+ * malformed pattern.
+ */
+export async function packBuildContext(folder, recipe) {
+    const root = path.resolve(folder);
+    if (!existsSync(root) || !statSync(root).isDirectory()) {
+        throw new Error(`The build context '${folder}' is not a folder.`);
+    }
+    const recipePath = path.resolve(root, recipe ?? defaultRecipe(root));
+    const inside = pathInside(root, recipePath);
+    if (inside === undefined && !existsSync(recipePath)) {
+        throw new Error(`The recipe '${recipePath}' does not exist.`);
+    }
+    const ignoreFile = ignoreFileFor(root, recipePath);
+    const entries = await contextEntries(root, inside, ignoreFile);
+    const recipeName = inside ?? OutsideRecipePrefix + randomBytes(OutsideRecipeRandomBytes).toString("hex");
+    if (inside === undefined) {
+        entries.push({ source: recipePath, name: recipeName });
+        // Only a recipe's own ignore file lies outside the folder; the root one is already among the entries.
+        if (pathInside(root, ignoreFile) === undefined) {
+            entries.push({ source: ignoreFile, name: recipeName + ignoreFile.slice(recipePath.length) });
+        }
+    }
+    return { archive: await ArchiveFile.write(entries), recipe: recipeName };
+}
+/**
+ * Lists the entries of a context folder that a build sends, each folder followed by what it holds, in ordinal order of name within
+ * each folder. `compose up` sends each service's build context with the same entries.
+ *
+ * @param root - The context folder's full path.
+ * @param recipe - The recipe's path inside the folder, with `/` separators, or undefined when it lies outside.
+ * @param ignoreFile - The ignore file's full path, which may not exist.
+ * @returns Each entry's full path and its path inside the folder; a folder's path ends in `/`.
+ */
+export async function contextEntries(root, recipe, ignoreFile) {
+    const ignore = existsSync(ignoreFile) ? DockerIgnore.parse(await readFile(ignoreFile, "utf8"), ignoreFile) : DockerIgnore.empty;
+    const alwaysSent = new Set([recipe, pathInside(root, ignoreFile)].filter((name) => name !== undefined));
+    const entries = [];
+    await collectEntries(root, "", ignore, alwaysSent, entries);
+    return entries;
+}
+/**
+ * Gives the recipe of a build that names none, as the `endia` CLI chooses it: `Endiafile` at the root of the context folder when it
+ * exists, and `Dockerfile` otherwise.
+ *
+ * @param root - The context folder's full path.
+ * @returns The recipe's file name.
+ */
+export function defaultRecipe(root) {
+    return isFile(path.join(root, Endiafile)) ? Endiafile : Dockerfile;
+}
+/**
+ * Gives the ignore file that applies to a recipe, as the `endia` CLI chooses it: the first of these that exists. A recipe's own
+ * ignore file is named as the recipe's file name followed by the ignore file's name, beside the recipe.
+ *
+ * 1. The recipe's own `.endiaignore`.
+ * 2. The recipe's own `.dockerignore`.
+ * 3. `.endiaignore` at the root of the folder.
+ * 4. `.dockerignore` at the root of the folder.
+ *
+ * @param root - The context folder's full path.
+ * @param recipe - The recipe's full path.
+ * @returns The ignore file's full path; `.dockerignore` at the root, which does not exist, when none of the four exists.
+ */
+export function ignoreFileFor(root, recipe) {
+    const candidates = [recipe + EndiaIgnoreFileName, recipe + IgnoreFileName, path.join(root, EndiaIgnoreFileName), path.join(root, IgnoreFileName)];
+    return candidates.find(isFile) ?? path.join(root, IgnoreFileName);
+}
+function isFile(file) {
+    return existsSync(file) && statSync(file).isFile();
+}
+/**
+ * Gives a path's place inside a folder.
+ *
+ * @param root - The folder's full path.
+ * @param target - A full path.
+ * @returns The path inside the folder with `/` separators, or undefined when it lies outside the folder.
+ */
+export function pathInside(root, target) {
+    const relative = path.relative(root, target).split(path.sep).join("/");
+    return relative === ".." || relative.startsWith("../") || path.isAbsolute(relative) ? undefined : relative;
+}
+// Lists a folder's entries and, for each sub-folder that needs it, the sub-folder's entries. A sub-folder the ignore file leaves out
+// is still listed when the recipe or the ignore file lies under it, or when the ignore file has a `!` line, which could re-include a
+// file under it; Docker's own walk does the same. A link is never followed.
+async function collectEntries(folder, prefix, ignore, alwaysSent, entries) {
+    const names = (await readdir(folder)).sort(compareOrdinal);
+    for (const name of names) {
+        const relative = prefix + name;
+        const source = path.join(folder, name);
+        const item = await lstat(source);
+        const sent = alwaysSent.has(relative) || !ignore.isIgnored(relative);
+        const walked = item.isDirectory() && (sent || ignore.reincludes || [...alwaysSent].some((kept) => kept.startsWith(`${relative}/`)));
+        if (sent) {
+            entries.push({ source, name: item.isDirectory() ? `${relative}/` : relative });
+        }
+        if (walked) {
+            await collectEntries(source, `${relative}/`, ignore, alwaysSent, entries);
+        }
+    }
+}
+// Ordinal order compares UTF-16 code units, as the CLI orders names, rather than the locale's order.
+function compareOrdinal(first, second) {
+    return first < second ? -1 : first > second ? 1 : 0;
+}

package/dist/archives/docker-ignore.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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 declare const IgnoreFileName = ".dockerignore";
+/** EastIndia's name for an ignore file, which a build reads in preference to a `.dockerignore` in the same place. */
+export declare const EndiaIgnoreFileName = ".endiaignore";
+/**
+ * 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 declare class DockerIgnore {
+    private readonly patterns;
+    private constructor();
+    /** An ignore file that excludes nothing, for a context without one. */
+    static readonly empty: 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: string, file?: string): DockerIgnore;
+    /**
+     * 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(): boolean;
+    /**
+     * 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: string): boolean;
+}
+/**
+ * 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 declare function cleanPath(path: string): string;