@promigence/sdk 0.1.0-beta.4 → 0.1.0-beta.6

package/dist/cjs/client.d.ts

@@ -5,7 +5,7 @@ import { type Bundle } from "./bundle.js";
 import { type PtyExit, type PtySession } from "./pty.js";
 import { type SshTunnel } from "./ssh.js";
 import type * as M from "./models.gen.js";
-import { type GithubConnect, type GithubDisconnected, type GithubRepos, type GithubStatus, type GithubUntracked } from "./github.js";
+import { type ConnectRequest, type ConnectTicket, type GithubConnect, type GithubDisconnected, type GithubRepos, type GithubStatus, type GithubUntracked } from "./github.js";
 import { type GitlabConnect, type GitlabDisconnected, type GitlabRepos, type GitlabStatus, type GitlabUntracked } from "./gitlab.js";
 export type FetchLike = typeof globalThis.fetch;
 /**
@@ -343,7 +343,8 @@ export interface RunReport {
     [extra: string]: unknown;
 }
 /** A build of a snapshot (`POST /snapshots`, `GET /snapshots/builds/:id`). */
-export type BuildState = "queued" | "running" | "verified" | "rejected" | "failed";
+/** `built`: finished and stored with no verification command to run; done, like `verified`. */
+export type BuildState = "queued" | "running" | "verified" | "built" | "rejected" | "failed";
 export interface SecretRecord {
     name: string;
     /** Length of the stored value, so a caller can sanity-check without reading it. */
@@ -353,9 +354,9 @@ export interface SecretRecord {
     updated_at?: string;
     /**
      * The hosts the secret is bound to. Absent when it is not bound: a sandbox that names it is
-     * then given the value. When present, the sandbox never sees the value: requests it sends to the
-     * host's address in `urls` are authenticated with the secret; a request made straight to
-     * `https://<host>/` is not.
+     * then given the value. When present, requests the sandbox sends to the host's address in
+     * `urls` are authenticated with the secret, a request made straight to `https://<host>/` is not,
+     * and the value stays out of the sandbox unless a run asks for it (`raw`).
      */
     hosts?: string[];
     /**
@@ -364,7 +365,7 @@ export interface SecretRecord {
      */
     urls?: string[];
     /**
-     * The variables a sandbox that names this secret is also given, each pointed at its host's
+     * The variables a sandbox that names this secret is also given, each set to its host's
      * address in `urls`: `OPENAI_BASE_URL` for `api.openai.com`, `ANTHROPIC_BASE_URL` for
      * `api.anthropic.com`. Absent when there is none. A variable the caller sets itself wins.
      */
@@ -379,10 +380,10 @@ export interface SecretRecord {
     scan_responses?: boolean;
 }
 /**
- * `secrets.set` options: bind the secret to hosts. A sandbox that names a bound secret never sees
- * its value: requests it sends to the host's address the answer gives in `urls` (and to
- * `$OPENAI_BASE_URL` / `$ANTHROPIC_BASE_URL` for those providers) are authenticated with it, and
- * one sent straight to the host is not.
+ * `secrets.set` options: bind the secret to hosts. Requests a sandbox sends to the host's address
+ * the answer gives in `urls` (and to `$OPENAI_BASE_URL` / `$ANTHROPIC_BASE_URL` for those
+ * providers) are authenticated with it, one sent straight to the host is not, and the value stays
+ * out of the sandbox unless a run asks for it (`raw: "refused"` forbids that; the default allows it).
  *
  * Every option left out keeps what the secret already has, so setting a bound secret again with
  * a new value (a rotation) keeps its binding. `hosts: []` removes it.
@@ -1478,8 +1479,8 @@ export interface SandboxNetworkCut {
  * secrets: ["OPENAI_API_KEY", { name: "work_secret_7", as: "ANTHROPIC_WORK_SECRET" }]
  * ```
  *
- * A secret bound to hosts (`secrets.set(name, value, { hosts })`) arrives as its placeholder;
- * `mode: "raw"` asks for the value itself, and is refused for one stored with `raw: "refused"`.
+ * A secret bound to hosts (`secrets.set(name, value, { hosts })`) does not put its value in the
+ * sandbox; `mode: "raw"` asks for the value itself, and is refused for one stored with `raw: "refused"`.
  */
 export type SecretBinding = string | {
     name: string;
@@ -1649,6 +1650,14 @@ export interface SnapshotCreateOpts {
     verify?: VerifySpec;
     /** Image forms: a background process started before the snapshot, so forks inherit it running. */
     start?: string | string[];
+    /**
+     * Image and Dockerfile forms: environment variables for every command, terminal and SSH
+     * session in this snapshot's sandboxes (and its own setup, verify and start), set over the
+     * image's `ENV` as `docker run -e` sets them. A value may build on what the image sets with
+     * `${containerEnv:NAME}` (or `${containerEnv:NAME:default}`):
+     * `{ PATH: "${containerEnv:PATH}:/opt/tools/bin" }`.
+     */
+    env?: Record<string, string>;
     tier?: Tier;
     /** Image forms: the name of a stored secret holding the registry credentials. */
     registrySecret?: string;
@@ -1772,28 +1781,6 @@ export declare function imageRefNamesVersion(image: string): boolean;
 export declare function checkImageVersioned(image: string): void;
 /** A git context, pinned: `https://github.com/org/app@<40 hex>`. A branch is not a pin. */
 export declare const CONTEXT_GIT_RE: RegExp;
-/** The prefix a packed directory travels under. */
-export declare const CONTEXT_TAR_PREFIX = "tar;base64,";
-/**
- * Directories never worth sending. `.dockerignore` is **not** applied to a context that fits: it
- * is sent with the context and the build applies it, so honouring it twice could only disagree
- * with the build. The cost is that editing an ignored file still changes the snapshot's
- * identity, which is the safe direction to be wrong in. Only a context over the limit — one that
- * would be refused anyway — is packed again without what its `.dockerignore` excludes.
- */
-export declare const CONTEXT_SKIP: Set<string>;
-/**
- * A `.dockerignore`, as the build reads it: one pattern a line, `#` comments, `!` re-includes,
- * Go `filepath.Match` syntax plus `**`, anchored at the context root, and a pattern that matches a
- * directory matches everything under it. The last pattern that matches a path decides. Returns
- * `undefined` for a file with no patterns.
- */
-export declare function dockerignoreMatcher(text: string): {
-    ignored: (rel: string) => boolean;
-    exceptions: boolean;
-} | undefined;
-/** The server's limit, refused here so a 9 MB context does not cross the wire to be told no. */
-export declare const CONTEXT_MAX_BYTES: number;
 /**
  * What in a repository URL can carry a credential: a user name, password or token (`https://TOKEN@…`,
  * `https://user:pass@…`, `:token@`, a percent-encoded `@`, any `@` in a scheme URL, the scp form's
@@ -1813,19 +1800,6 @@ export declare const REPO_CREDENTIALS_FIX: string;
 export declare function checkRepoUrl(url: unknown, field: string): void;
 /** Refuse a context that is neither a pinned git URL nor a packed directory. */
 export declare function checkDockerfileContext(context: unknown): asserts context is string;
-/**
- * Pack a directory into the string `dockerfile.context` takes.
- *
- * The archive is only transport: the snapshot's identity is computed from the *entries* server
- * side, so this does not have to agree byte-for-byte with `sdk-py`'s packer — and two calls on
- * an unchanged directory give the same snapshot either way.
- */
-export declare function packContext(dir: string, opts?: {
-    maxBytes?: number;
-    keep?: readonly string[];
-}): string;
-/** The Dockerfile's path as the context sees it, for `dockerfile.path`. */
-export declare function contextRelative(contextDir: string, dockerfilePath: string): string;
 /**
  * The `POST /snapshots` body for one of its three forms; throws `InvalidArgumentError` before
  * anything is sent. Kept field-for-field with `sdk-py` (`_ops.snapshot_create_body`) so the two
@@ -2115,6 +2089,14 @@ export declare class PromigenceClient {
         status: () => Promise<GithubStatus>;
         /** `POST /integrations/github/connect` — the install link (15 minutes); open it in a browser. */
         connect: () => Promise<GithubConnect>;
+        /**
+         * `POST /integrations/github/requests` — a connection started for you in the console: open
+         * `connect_url` in a browser signed in to the console as you (a 404 means the console cannot start
+         * it here: use `connect()`).
+         */
+        ticket: () => Promise<ConnectTicket>;
+        /** `GET /integrations/github/requests/:id` — one of your connection requests: `pending`, or how it ended. */
+        request: (requestId: string) => Promise<ConnectRequest>;
         /** `DELETE /integrations/github/installations/:id` — nothing is built from that account any more. */
         disconnect: (installationId: number | string) => Promise<GithubDisconnected>;
         /** `GET /integrations/github/repos` — one page (at most 100) across every connection. */
@@ -2135,6 +2117,14 @@ export declare class PromigenceClient {
         status: () => Promise<GitlabStatus>;
         /** `POST /integrations/gitlab/connect` — the authorize link (15 minutes); open it in a browser. */
         connect: () => Promise<GitlabConnect>;
+        /**
+         * `POST /integrations/gitlab/requests` — a connection started for you in the console: open
+         * `connect_url` in a browser signed in to the console as you (a 404 means the console cannot start
+         * it here: use `connect()`).
+         */
+        ticket: () => Promise<ConnectTicket>;
+        /** `GET /integrations/gitlab/requests/:id` — one of your connection requests: `pending`, or how it ended. */
+        request: (requestId: string) => Promise<ConnectRequest>;
         /** `DELETE /integrations/gitlab/connections/:id` — revoked on GitLab; nothing is built through it any more. */
         disconnect: (connectionId: string) => Promise<GitlabDisconnected>;
         /** `GET /integrations/gitlab/repos` — one page (at most 100) of one connection's projects. */
@@ -2636,6 +2626,9 @@ export declare class PromigenceClient {
              * A failure mid-loop leaves a **prefix** in the sandbox, not a corrupt file, and the
              * thrown error carries how far it got (`written` in the error's evidence).
              * Re-running the same `put` is safe: chunk 0 truncates.
+             *
+             * `mode` (`0o755`) sets the file's permission bits. Without it a file that already exists
+             * keeps its mode, as a shell `>` does, and a new one is `0o644`.
              */
             put: (sandboxId: string, path: string, data: string | Uint8Array, opts?: {
                 mode?: number;

package/dist/cjs/client.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PromigenceClient = exports.LONG_POLL_MS = exports.REPO_CREDENTIALS_FIX = exports.CONTEXT_MAX_BYTES = exports.CONTEXT_SKIP = exports.CONTEXT_TAR_PREFIX = exports.CONTEXT_GIT_RE = exports.IMAGE_DIGEST_RE = exports.MAX_SOURCES = exports.NOTICE_HEADER = exports.isWaiting = exports.FILE_TIMEOUT_MS = void 0;
+exports.PromigenceClient = exports.LONG_POLL_MS = exports.REPO_CREDENTIALS_FIX = exports.CONTEXT_GIT_RE = exports.IMAGE_DIGEST_RE = exports.MAX_SOURCES = exports.NOTICE_HEADER = exports.isWaiting = exports.FILE_TIMEOUT_MS = void 0;
 exports.execOutputBytes = execOutputBytes;
 exports.configDir = configDir;
 exports.credentialsPath = credentialsPath;
@@ -18,13 +18,10 @@ exports.imageRefProblem = imageRefProblem;
 exports.checkImageRef = checkImageRef;
 exports.imageRefNamesVersion = imageRefNamesVersion;
 exports.checkImageVersioned = checkImageVersioned;
-exports.dockerignoreMatcher = dockerignoreMatcher;
 exports.repoUrlCredential = repoUrlCredential;
 exports.withoutPin = withoutPin;
 exports.checkRepoUrl = checkRepoUrl;
 exports.checkDockerfileContext = checkDockerfileContext;
-exports.packContext = packContext;
-exports.contextRelative = contextRelative;
 exports.snapshotCreateBody = snapshotCreateBody;
 exports.errorFor = errorFor;
 exports.isKeyedCreate = isKeyedCreate;
@@ -44,6 +41,7 @@ const caller_js_1 = require("./caller.js");
 const pty_js_1 = require("./pty.js");
 const ssh_js_1 = require("./ssh.js");
 const http2_js_1 = require("./http2.js");
+const context_js_1 = require("./context.js");
 const proxy_js_1 = require("./proxy.js");
 const trace_js_1 = require("./trace.js");
 const keyed_gen_js_1 = require("./keyed.gen.js");
@@ -443,81 +441,6 @@ function checkImageVersioned(image) {
     throw new core_js_1.InvalidArgumentError(`image ${JSON.stringify(ref)} names no tag or digest, so it would be pinned to whatever ${ref}:latest is today`, `Name the version: a tag (${ref}:<version>), ${ref}:latest if you mean the moving tag, or a digest (${ref}@sha256:<64 hex>).`);
 }
 exports.CONTEXT_GIT_RE = /^(?:https?:\/\/|ssh:\/\/|git:\/\/|git@)\S+@[0-9a-f]{40}$/i;
-exports.CONTEXT_TAR_PREFIX = "tar;base64,";
-exports.CONTEXT_SKIP = new Set([".git", "node_modules", "__pycache__", ".venv", ".DS_Store"]);
-function dockerignoreMatcher(text) {
-    const rules = [];
-    for (const raw of text.split(/\r?\n/)) {
-        let line = raw.trim();
-        if (!line || line.startsWith("#"))
-            continue;
-        const exclusion = line.startsWith("!");
-        if (exclusion)
-            line = line.slice(1).trim();
-        const parts = [];
-        for (const seg of line.split("/")) {
-            if (seg === "" || seg === ".")
-                continue;
-            if (seg === "..")
-                parts.pop();
-            else
-                parts.push(seg);
-        }
-        const pattern = parts.join("/");
-        if (!pattern)
-            continue;
-        let re = "^";
-        for (let i = 0; i < pattern.length; i++) {
-            const ch = pattern[i];
-            if (ch === "*") {
-                if (pattern[i + 1] === "*") {
-                    i++;
-                    if (pattern[i + 1] === "/")
-                        i++;
-                    re += i + 1 >= pattern.length ? ".*" : "(.*/)?";
-                }
-                else {
-                    re += "[^/]*";
-                }
-            }
-            else if (ch === "?") {
-                re += "[^/]";
-            }
-            else if (ch === "\\") {
-                re += i + 1 < pattern.length ? `\\${pattern[++i]}` : "\\\\";
-            }
-            else if (ch === "[" || ch === "]") {
-                re += ch;
-            }
-            else {
-                re += /[.+()|{}$]/.test(ch) ? `\\${ch}` : ch;
-            }
-        }
-        try {
-            rules.push({ re: new RegExp(`${re}$`), exclusion });
-        }
-        catch {
-        }
-    }
-    if (rules.length === 0)
-        return undefined;
-    const ignored = (rel) => {
-        const dirs = rel.split("/");
-        let matched = false;
-        for (const r of rules) {
-            if (r.exclusion !== matched)
-                continue;
-            let hit = r.re.test(rel);
-            for (let i = 1; !hit && i < dirs.length; i++)
-                hit = r.re.test(dirs.slice(0, i).join("/"));
-            if (hit)
-                matched = !r.exclusion;
-        }
-        return matched;
-    };
-    return { ignored, exceptions: rules.some((r) => r.exclusion) };
-}
-exports.CONTEXT_MAX_BYTES = 8 * 1024 * 1024;
 function repoUrlCredential(url) {
     const u = url.trim();
     const sep = u.indexOf("://");
@@ -556,123 +479,17 @@ function checkRepoUrl(url, field) {
 }
 function checkDockerfileContext(context) {
     const c = typeof context === "string" ? context.trim() : "";
-    if (!c.startsWith(exports.CONTEXT_TAR_PREFIX))
+    if (!c.startsWith(context_js_1.CONTEXT_TAR_PREFIX))
         checkRepoUrl(withoutPin(c), "dockerfile.context");
     if (!c) {
         throw new core_js_1.InvalidArgumentError("snapshots.create dockerfile needs a context", "Pass { dockerfile: { context: 'https://github.com/org/app@<40-char sha>', path: 'Dockerfile' } }, " +
             "or pack a directory with packContext('./app').");
     }
-    if (c.startsWith(exports.CONTEXT_TAR_PREFIX) || exports.CONTEXT_GIT_RE.test(c))
+    if (c.startsWith(context_js_1.CONTEXT_TAR_PREFIX) || exports.CONTEXT_GIT_RE.test(c))
         return;
     throw new core_js_1.InvalidArgumentError(`dockerfile.context must be a git URL pinned to a full 40-character sha, got ${JSON.stringify(context)}`, "A branch or a tag is not a pin: pass URL@<40-char sha> (git rev-parse HEAD), or pack a local " +
         "directory with packContext('./app').");
 }
-function packContext(dir, opts = {}) {
-    const max = opts.maxBytes ?? exports.CONTEXT_MAX_BYTES;
-    const keep = new Set([".dockerignore", ...(opts.keep ?? [])]);
-    const collect = (ignore) => {
-        const entries = [];
-        let total = 0;
-        const walk = (abs, rel) => {
-            for (const name of (0, node_fs_1.readdirSync)(abs).sort()) {
-                if (exports.CONTEXT_SKIP.has(name))
-                    continue;
-                const childAbs = (0, node_path_1.join)(abs, name);
-                const childRel = rel ? `${rel}/${name}` : name;
-                const st = (0, node_fs_1.lstatSync)(childAbs);
-                const dropped = ignore !== undefined && !keep.has(childRel) && ignore.ignored(childRel);
-                if (st.isDirectory()) {
-                    if (dropped && !ignore.exceptions)
-                        continue;
-                    if (!walk(childAbs, childRel))
-                        return false;
-                    continue;
-                }
-                if (dropped)
-                    continue;
-                if (st.isSymbolicLink()) {
-                    entries.push({ path: childRel, mode: 0o777, body: Buffer.alloc(0), link: (0, node_fs_1.readlinkSync)(childAbs) });
-                    continue;
-                }
-                if (!st.isFile())
-                    continue;
-                total += st.size;
-                if (total > max)
-                    return false;
-                entries.push({ path: childRel, mode: st.mode & 0o111 ? 0o755 : 0o644, body: (0, node_fs_1.readFileSync)(childAbs) });
-            }
-            return true;
-        };
-        return walk(dir, "") ? entries : undefined;
-    };
-    let entries = collect();
-    if (entries === undefined) {
-        let ignore;
-        try {
-            ignore = dockerignoreMatcher((0, node_fs_1.readFileSync)((0, node_path_1.join)(dir, ".dockerignore"), "utf8"));
-        }
-        catch {
-            ignore = undefined;
-        }
-        if (ignore !== undefined)
-            entries = collect(ignore);
-        if (entries === undefined) {
-            throw new core_js_1.InvalidArgumentError(`the build context is over ${max} bytes${ignore ? " even without what its .dockerignore excludes" : ""}`, `${ignore ? "Exclude more in .dockerignore" : "Add a .dockerignore"}, point --context at a smaller directory, or pass a git URL pinned to a full 40-character sha.`);
-        }
-    }
-    if (entries.length === 0) {
-        throw new core_js_1.InvalidArgumentError(`the build context ${JSON.stringify(dir)} is empty`, "Point --context at the directory holding your Dockerfile.");
-    }
-    return exports.CONTEXT_TAR_PREFIX + tarOf(entries).toString("base64");
-}
-function contextRelative(contextDir, dockerfilePath) {
-    const rel = (0, node_path_1.relative)(contextDir, dockerfilePath).split(node_path_1.sep).join("/");
-    if (!rel || rel.startsWith("..")) {
-        throw new core_js_1.InvalidArgumentError(`${JSON.stringify(dockerfilePath)} is not inside the context ${JSON.stringify(contextDir)}`, "Pass --context DIR with the Dockerfile underneath it.");
-    }
-    return rel;
-}
-function tarOf(entries) {
-    const out = [];
-    for (const e of [...entries].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))) {
-        const head = Buffer.alloc(512);
-        let name = e.path;
-        let prefix = "";
-        if (Buffer.byteLength(name) > 100) {
-            const cut = name.lastIndexOf("/", name.length - 100);
-            if (cut <= 0 || Buffer.byteLength(name.slice(cut + 1)) > 100 || Buffer.byteLength(name.slice(0, cut)) > 155) {
-                throw new core_js_1.InvalidArgumentError(`the path ${JSON.stringify(e.path)} is too long for a build context`, "Shorten the path or pass a git URL pinned to a full 40-character sha.");
-            }
-            prefix = name.slice(0, cut);
-            name = name.slice(cut + 1);
-        }
-        const put = (s, at, len) => { head.write(s.slice(0, len), at, len, "utf8"); };
-        const oct = (n, at, len) => { put(n.toString(8).padStart(len - 1, "0") + "\0", at, len); };
-        put(name, 0, 100);
-        oct(e.mode, 100, 8);
-        oct(0, 108, 8);
-        oct(0, 116, 8);
-        oct(e.link === undefined ? e.body.length : 0, 124, 12);
-        oct(0, 136, 12);
-        head.write("        ", 148, 8, "utf8");
-        head.write(e.link === undefined ? "0" : "2", 156, 1, "utf8");
-        if (e.link !== undefined)
-            put(e.link, 157, 100);
-        head.write("ustar\0", 257, 6, "binary");
-        head.write("00", 263, 2, "utf8");
-        put(prefix, 345, 155);
-        let sum = 0;
-        for (const b of head)
-            sum += b;
-        put(sum.toString(8).padStart(6, "0") + "\0 ", 148, 8);
-        out.push(head);
-        if (e.link === undefined && e.body.length > 0) {
-            out.push(e.body, Buffer.alloc((512 - (e.body.length % 512)) % 512));
-        }
-    }
-    out.push(Buffer.alloc(1024));
-    return Buffer.concat(out);
-}
 function sourcesBody(sources) {
     if (sources.length > exports.MAX_SOURCES) {
         throw new core_js_1.InvalidArgumentError(`snapshots.create takes at most ${exports.MAX_SOURCES} extra sources, got ${sources.length}`, "An environment assembled from more repositories than that is cheaper to build once as " +
@@ -720,6 +537,9 @@ function snapshotCreateBody(opts) {
     let body;
     const github = typeof o.repo === "string"
         && (o.repo.trim().startsWith(github_js_1.GITHUB_REPO_PREFIX) || o.repo.trim().startsWith(gitlab_js_1.GITLAB_REPO_PREFIX));
+    if (o.env !== undefined && Object.keys(o.env).length && forms[0] === "repo") {
+        throw new core_js_1.InvalidArgumentError("snapshots.create env is for an image or a Dockerfile", "A repository snapshot sets its environment in its setup steps, or pass env on each command.");
+    }
     if (!github && (o.ref !== undefined || o.from !== undefined || o.track)) {
         throw new core_js_1.InvalidArgumentError("snapshots.create ref, from and track are for a connected repository (repo: 'github:owner/name' or 'gitlab:group/project')", "Pass { repo: 'github:your-org/app', ref: 'main' }, or drop them for this form.");
     }
@@ -775,6 +595,8 @@ function snapshotCreateBody(opts) {
             body["tier"] = o.tier;
         if (o.registrySecret)
             body["registry_secret"] = o.registrySecret;
+        if (o.env !== undefined && Object.keys(o.env).length)
+            body["env"] = { ...o.env };
     }
     if (o.alias)
         body["alias"] = o.alias;
@@ -1521,6 +1343,11 @@ class PromigenceClient {
     github = {
         status: () => this.request({ method: "GET", path: "/integrations/github" }),
         connect: () => this.request({ method: "POST", path: "/integrations/github/connect", body: {} }),
+        ticket: () => this.request({ method: "POST", path: "/integrations/github/requests", body: {} }),
+        request: (requestId) => this.request({
+            method: "GET",
+            path: `/integrations/github/requests/${encodeURIComponent(requestId)}`,
+        }),
         disconnect: (installationId) => this.request({
             method: "DELETE",
             path: `/integrations/github/installations/${encodeURIComponent(String(installationId))}`,
@@ -1539,6 +1366,11 @@ class PromigenceClient {
     gitlab = {
         status: () => this.request({ method: "GET", path: "/integrations/gitlab" }),
         connect: () => this.request({ method: "POST", path: "/integrations/gitlab/connect", body: {} }),
+        ticket: () => this.request({ method: "POST", path: "/integrations/gitlab/requests", body: {} }),
+        request: (requestId) => this.request({
+            method: "GET",
+            path: `/integrations/gitlab/requests/${encodeURIComponent(requestId)}`,
+        }),
         disconnect: (connectionId) => this.request({
             method: "DELETE",
             path: `/integrations/gitlab/connections/${encodeURIComponent(connectionId)}`,

package/dist/cjs/context.d.ts

@@ -0,0 +1,119 @@
+/**
+ * A local directory as a Dockerfile build context: what `packContext` sends, decided before
+ * anything leaves this machine.
+ *
+ * - **`.dockerignore` is applied here, always**, with the rules `docker build` uses: Go glob syntax
+ *   plus `**`, `!` to bring a path back, the last matching line wins, a matched directory takes
+ *   everything under it, and paths are read from the context root. A file the `.dockerignore`
+ *   excludes is never uploaded. `<Dockerfile>.dockerignore` beside the Dockerfile is read instead
+ *   of the root `.dockerignore` when it exists, as `docker build` does. The Dockerfile and the
+ *   ignore files themselves are always sent, whatever a pattern says.
+ * - **`.git` is never sent** unless the `.dockerignore` has the line `!.git`: git history can hold
+ *   credentials long deleted from the tree.
+ * - **Without a `.dockerignore`**, `node_modules`, `__pycache__`, `.venv` and `.DS_Store` are left
+ *   out too, and a note says so; with one, only what it lists is left out.
+ * - Empty directories and permission bits travel as they are on disk; a set-user-ID or
+ *   set-group-ID bit is cleared, with a note.
+ * - Files that look like credentials (`.env`, private keys, cloud credentials, ...) are refused,
+ *   by name, unless `allowSecrets` says otherwise. The check goes by file name: it is
+ *   best-effort and cannot see what a file holds, so look over the list (`listContext`) before
+ *   you send a directory.
+ * - Symbolic links travel as links, never as the file they point at.
+ */
+/** The prefix a packed directory travels under in `dockerfile.context`. */
+export declare const CONTEXT_TAR_PREFIX = "tar;base64,";
+/** The largest context accepted, counted in file bytes after `.dockerignore`. */
+export declare const CONTEXT_MAX_BYTES: number;
+/**
+ * Names left out when the context has no `.dockerignore`. With one, the `.dockerignore` alone
+ * decides, except for `.git` (sent only when it says `!.git`).
+ */
+export declare const CONTEXT_SKIP: Set<string>;
+/** The patterns of one ignore file, compiled. */
+export interface DockerIgnore {
+    /** The ignore file these came from (`.dockerignore` or `<Dockerfile>.dockerignore`). */
+    readonly file: string;
+    /** The patterns as the build holds them, in file order: cleaned, an exception keeping its `!`. */
+    readonly patterns: readonly string[];
+    /** Whether any line is a `!` exception. */
+    readonly exceptions: boolean;
+    /** Whether a line says `!.git`, which is what sends `.git`. */
+    readonly sendsGit: boolean;
+    /**
+     * Is `path` (relative to the context root, `/`-separated) left out? The last pattern that
+     * matches it, or one of the directories above it, decides.
+     */
+    ignored(path: string): boolean;
+}
+/**
+ * Read an ignore file the way `docker build` reads it: a UTF-8 BOM is dropped; a line starting
+ * with `#` is a comment; each line is trimmed; `!` starts an exception; each pattern is cleaned
+ * (`a//b/../c` is `a/c`) and a leading `/` is dropped. A line the build cannot read (a lone `!`,
+ * an unclosed `[`, a trailing `\`) makes the build refuse the whole file, so it is refused here,
+ * naming the line, before anything is sent.
+ */
+export declare function parseDockerignore(text: string, file?: string): DockerIgnore;
+/**
+ * A `.dockerignore`'s patterns as a predicate, or `undefined` for a file with no patterns. Refuses
+ * a file the build could not read. Kept for code written against 0.1; `parseDockerignore` is the
+ * full reader.
+ */
+export declare function dockerignoreMatcher(text: string): {
+    ignored: (rel: string) => boolean;
+    exceptions: boolean;
+} | undefined;
+/**
+ * Does this path look like a credential (`.env`, a private key, cloud or registry credentials, a
+ * token file, ...)? By name only: best-effort, it cannot see what a file holds. Templates such as
+ * `.env.example` are not.
+ */
+export declare function secretLike(path: string): boolean;
+/** What a build context is packed from and sent with. */
+export interface ContextOptions {
+    /**
+     * The Dockerfile's path inside the context, `/`-separated (default `Dockerfile`). It is always
+     * sent, and `<it>.dockerignore`, when present, is read instead of the root `.dockerignore`.
+     */
+    dockerfile?: string;
+    /** More paths inside the context to send whatever `.dockerignore` says. */
+    keep?: readonly string[];
+    /** Refuse a context whose files add up to more than this many bytes (default `CONTEXT_MAX_BYTES`). */
+    maxBytes?: number;
+    /**
+     * Send files that look like credentials. Default `false`: they are refused, by name, and
+     * nothing is sent.
+     */
+    allowSecrets?: boolean;
+    /** Called with each note: what was left out by default, or changed on the way. */
+    onNote?: (note: string) => void;
+}
+/** What a build context would hold, before anything is sent. */
+export interface ContextListing {
+    /** Every path that would be sent, sorted; a directory's ends in `/`. */
+    paths: string[];
+    /** How many of them are files or links. */
+    files: number;
+    /** The files' bytes. */
+    bytes: number;
+    /** What was left out by default or changed on the way, one sentence each. */
+    notes: string[];
+    /** The paths that would be sent and look like credentials. */
+    secrets: string[];
+    /** The ignore file applied, or `null` when there is none. */
+    ignoreFile: string | null;
+}
+/**
+ * What `packContext(dir, opts)` would send, without sending or packing anything: every path, the
+ * notes, and the files that look like credentials. Refuses only what `packContext` cannot read
+ * (an ignore file the build would refuse).
+ */
+export declare function listContext(dir: string, opts?: ContextOptions): ContextListing;
+/**
+ * Pack a directory into the string `dockerfile.context` takes. What is sent is decided here (see
+ * the module notes): files the `.dockerignore` excludes, and `.git`, are never uploaded; files
+ * that look like credentials are refused unless `allowSecrets`; a context over `maxBytes` after
+ * `.dockerignore` is refused. The same tree packs to the same snapshot whichever SDK packs it.
+ */
+export declare function packContext(dir: string, opts?: ContextOptions): string;
+/** The Dockerfile's path as the context sees it, for `dockerfile.path`. */
+export declare function contextRelative(contextDir: string, dockerfilePath: string): string;