@promigence/sdk 0.1.0-beta.12

package/dist/cjs/command-errors.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `CommandTimeoutError` — a command killed at its own `timeoutMs`.
+ *
+ * It is a `CommandExitError`, so a `catch (e) { if (e instanceof CommandExitError) … }` written
+ * against earlier releases still catches it, and `exitCode` is still the command's own (137, the
+ * SIGKILL at the deadline). What changes is what it says: `code` is `task_timeout`, the message
+ * names the bound, and `timedOut` is `true`. A command that exits 137 for any other reason (an
+ * out-of-memory kill, a `kill -9`) stays a plain `CommandExitError`.
+ */
+import { CommandExitError, type CommandResult } from "./core.js";
+/** `2000` → `"2 s"`, `1500` → `"1.5 s"`. */
+export declare function secondsText(ms: number): string;
+export declare class CommandTimeoutError extends CommandExitError {
+    /** Always `true`: the command ran past its own bound and was killed there. */
+    readonly timedOut: true;
+    /** The bound it ran into, in ms, when the SDK knows it. */
+    readonly timeoutMs: number | undefined;
+    readonly code: string;
+    readonly fix: string;
+    readonly guide: string;
+    constructor(result: CommandResult, timeoutMs: number | undefined);
+}
+/**
+ * Was this exec answer a command killed at its own timeout? The buffered and the streamed answer
+ * both say so (`timed_out`, `reason: "timeout"`).
+ */
+export declare function answerTimedOut(r: {
+    timed_out?: unknown;
+    reason?: unknown;
+} | undefined): boolean;
+/**
+ * The same question about a background command's exit record, which carries no `timed_out` of its
+ * own: a SIGKILL with no exit code whose running time reached the bound it was started with — the
+ * rule the API itself applies to a foreground command. Without a known bound, never.
+ */
+export declare function exitTimedOut(exit: {
+    exit_code?: number | null;
+    signal?: number | null;
+    wall_ms?: number;
+    timed_out?: unknown;
+} | undefined, timeoutMs: number | undefined): boolean;

package/dist/cjs/command-errors.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommandTimeoutError = void 0;
+exports.secondsText = secondsText;
+exports.answerTimedOut = answerTimedOut;
+exports.exitTimedOut = exitTimedOut;
+const core_js_1 = require("./core.js");
+const hint_js_1 = require("./hint.js");
+function secondsText(ms) {
+    const s = ms / 1000;
+    return `${Number.isInteger(s) ? s : Number(s.toFixed(3))} s`;
+}
+class CommandTimeoutError extends core_js_1.CommandExitError {
+    timedOut = true;
+    timeoutMs;
+    code;
+    fix;
+    guide;
+    constructor(result, timeoutMs) {
+        super(result);
+        this.code = "task_timeout";
+        this.timeoutMs = timeoutMs;
+        this.message = timeoutMs === undefined
+            ? `command timed out (killed at its timeout, exit ${result.exitCode})`
+            : `command timed out after ${secondsText(timeoutMs)} (killed at its timeoutMs bound of ${timeoutMs} ms, exit ${result.exitCode})`;
+        this.fix = "Give it longer: commands.run(cmd, { timeoutMs }) (unset, the bound is the sandbox's timeout, else 15 minutes). " +
+            "Pass { throwOnExit: false } to receive the result instead of this error.";
+        this.guide = `promigence agent-guide --section errors --code ${(0, hint_js_1.hintArg)(this.code)}`;
+    }
+}
+exports.CommandTimeoutError = CommandTimeoutError;
+function answerTimedOut(r) {
+    return r?.timed_out === true || r?.reason === "timeout";
+}
+function exitTimedOut(exit, timeoutMs) {
+    if (!exit)
+        return false;
+    if (exit.timed_out === true)
+        return true;
+    if (timeoutMs === undefined || typeof exit.wall_ms !== "number")
+        return false;
+    return (exit.exit_code === null || exit.exit_code === undefined) && exit.signal === 9 && exit.wall_ms + 1 >= timeoutMs;
+}

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;