@pipelex/sdk 0.32.0 → 0.34.0

package/dist/cli/bundle.js

@@ -0,0 +1,148 @@
+/**
+ * The bundle reader: a `--method` path read from disk into the files `run` sends inline.
+ *
+ * The rules are the command's contract, recorded as cases in `tests/fixtures/cli-cases.json` so
+ * that the Python twin reads a bundle the same way (`docs/cli.md`, "Reading a bundle"):
+ *
+ * - **A `.mthds` file** is a one-file bundle, sent under its own file name. A file of any other
+ *   name is refused.
+ * - **A directory** is every `.mthds` file under it, at any depth, each sent under its path
+ *   relative to the directory, with `/` between segments.
+ * - **The order** is the order of those names compared code point by code point, which is the
+ *   order of their UTF-8 bytes: `Zeta.mthds` before `main.mthds`, and `steps/score.mthds` before
+ *   `steps2.mthds`. A run sends the contents in this order, and the first of two files to declare
+ *   the same metadata is the one kept.
+ * - **A hidden entry**, a file or a directory whose name starts with `.`, is skipped, so a
+ *   `.venv/` or a `.git/` inside a bundle is never read.
+ * - **Any file not named `.mthds`** is ignored, Python files included: the command sends only
+ *   the MTHDS sources.
+ * - **A symbolic link** is judged by its own name: one named `.mthds` that leads to a file is read
+ *   through, under the link's name; one that leads to a directory is not descended into, which
+ *   keeps a link cycle from looping; and one that leads nowhere is refused. The `--method` path
+ *   itself may be a link, and is followed.
+ * - **A directory with no `.mthds` file** under it is refused, as is a file that is not UTF-8
+ *   text and a directory that cannot be listed. A byte-order mark is kept as the file's first
+ *   character, as it is on disk.
+ *
+ * Every refusal is a usage error, raised before any request.
+ */
+import { readdir, readFile, stat } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
+import { usageError } from "./io.js";
+/** The extension of a bundle's files. */
+export const BUNDLE_SUFFIX = ".mthds";
+const UTF8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+/**
+ * Read the bundle a `--method` path names, in the order the rules above give.
+ *
+ * @throws {CommandError} A usage error for a path that names no bundle.
+ */
+export async function readBundle(given) {
+    const absolute = resolve(given);
+    let found;
+    try {
+        found = await stat(absolute);
+    }
+    catch (error) {
+        throw usageError(`--method "${given}" is not a catalog id (mt_...), not an address (github.com/...), and no file or directory of that name exists.`, [`Reason: ${systemReason(error)}`]);
+    }
+    if (found.isDirectory()) {
+        const shown = given.replace(/\/+$/, "") || "/";
+        const entries = [];
+        await collect(absolute, "", shown, entries);
+        if (entries.length === 0) {
+            throw usageError(`--method "${given}" is a directory with no .mthds file under it.`);
+        }
+        entries.sort((left, right) => compareCodePoints(left.name, right.name));
+        const files = [];
+        for (const entry of entries) {
+            files.push({
+                name: entry.name,
+                content: await readText(entry.path, under(shown, entry.name)),
+            });
+        }
+        return files;
+    }
+    if (!found.isFile()) {
+        throw usageError(`--method "${given}" is neither a file nor a directory.`);
+    }
+    if (!basename(absolute).endsWith(BUNDLE_SUFFIX)) {
+        throw usageError(`--method "${given}" is not a .mthds file.`, [
+            "Name a .mthds file, a directory of them, an address (github.com/...) or a catalog id (mt_...).",
+        ]);
+    }
+    return [{ name: basename(absolute), content: await readText(absolute, given) }];
+}
+/** Gather the `.mthds` files under `directory`, each with its name relative to the bundle's root. */
+async function collect(directory, prefix, shownRoot, into) {
+    let entries;
+    try {
+        entries = await readdir(directory, { withFileTypes: true });
+    }
+    catch (error) {
+        throw usageError(`cannot list "${prefix === "" ? shownRoot : under(shownRoot, prefix.slice(0, -1))}".`, [`Reason: ${systemReason(error)}`]);
+    }
+    for (const entry of entries) {
+        if (entry.name.startsWith("."))
+            continue;
+        const name = `${prefix}${entry.name}`;
+        const path = join(directory, entry.name);
+        if (entry.isDirectory()) {
+            await collect(path, `${name}/`, shownRoot, into);
+        }
+        else if (entry.isSymbolicLink()) {
+            if (!entry.name.endsWith(BUNDLE_SUFFIX))
+                continue;
+            let target;
+            try {
+                target = await stat(path);
+            }
+            catch (error) {
+                throw usageError(`"${under(shownRoot, name)}" is a symbolic link that leads to no file.`, [
+                    `Reason: ${systemReason(error)}`,
+                ]);
+            }
+            if (target.isFile())
+                into.push({ name, path });
+        }
+        else if (entry.isFile() && entry.name.endsWith(BUNDLE_SUFFIX)) {
+            into.push({ name, path });
+        }
+    }
+}
+/**
+ * A path inside the bundle as the person would type it: the `--method` path as given, without
+ * its trailing `/`, then `/`, then the file's name in the bundle.
+ */
+function under(root, name) {
+    return `${root === "/" ? "" : root}/${name}`;
+}
+/** A bundle file's text, which must be UTF-8. */
+async function readText(path, shown) {
+    let bytes;
+    try {
+        bytes = await readFile(path);
+    }
+    catch (error) {
+        throw usageError(`cannot read "${shown}".`, [`Reason: ${systemReason(error)}`]);
+    }
+    try {
+        return UTF8.decode(bytes);
+    }
+    catch {
+        throw usageError(`"${shown}" is not UTF-8 text.`);
+    }
+}
+/** Compare two strings code point by code point, which is comparing their UTF-8 bytes. */
+export function compareCodePoints(left, right) {
+    return Buffer.compare(Buffer.from(left, "utf8"), Buffer.from(right, "utf8"));
+}
+/** The system's reason for a failed file operation: its code, else its message. */
+export function systemReason(error) {
+    if (error instanceof Error) {
+        const code = error.code;
+        return code ?? error.message;
+    }
+    return String(error);
+}
+//# sourceMappingURL=bundle.js.map

package/dist/cli/bundle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle.js","sourceRoot":"","sources":["../../src/cli/bundle.ts"],"names":[],"mappings":"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"}

package/dist/cli/environment.d.ts

@@ -0,0 +1,36 @@
+/**
+ * What the command reads from its environment, and the client it builds from it.
+ *
+ * The key comes from `PIPELEX_API_KEY` and nowhere else: a flag would put it in the shell's history
+ * and the process list. The API's address comes from `PIPELEX_BASE_URL`, the hosted API when it
+ * is not set. An empty variable counts as unset, except `PIPELEX_BASE_URL`: an empty one, such as
+ * an unfilled CI secret, reaches the SDK, which refuses it, rather than send the key to the hosted
+ * API by default. No `.env` file is read: a command started through `npx` from wherever the person
+ * stands would otherwise pick a credential from whichever file it found there.
+ */
+import { PipelexApiClient } from "../index.js";
+import type { CommandIO } from "./io.js";
+export declare const API_KEY_VARIABLE = "PIPELEX_API_KEY";
+export declare const BASE_URL_VARIABLE = "PIPELEX_BASE_URL";
+/**
+ * The poll interval in milliseconds, for tests only: the recorded case table sets it to `0`, so
+ * that a run answered "still running" is polled again at once. A person has no reason to set it;
+ * unset, the SDK's own interval applies. The Python command reads the same variable.
+ */
+export declare const POLL_INTERVAL_VARIABLE = "PIPELEX_SDK_POLL_INTERVAL_MS";
+/** The name the command gives itself in the `User-Agent` of every request, before the SDK's own. */
+export declare const CLIENT_APP_NAME = "pipelex-sdk-cli";
+/**
+ * The test-only poll interval, or `undefined` for the SDK's own.
+ *
+ * @throws {CommandError} A usage error when it is set to anything but a whole number.
+ */
+export declare function readPollInterval(io: CommandIO): number | undefined;
+/**
+ * The client every request goes through, built from the key and the base URL.
+ *
+ * @throws {CommandError} A usage error when the key is missing or the base URL is refused. The
+ *   refusal never quotes the key, and the SDK's refusal of a base URL never quotes the parts of it
+ *   that can carry a secret.
+ */
+export declare function makeClient(io: CommandIO): PipelexApiClient;

package/dist/cli/environment.js

@@ -0,0 +1,72 @@
+/**
+ * What the command reads from its environment, and the client it builds from it.
+ *
+ * The key comes from `PIPELEX_API_KEY` and nowhere else: a flag would put it in the shell's history
+ * and the process list. The API's address comes from `PIPELEX_BASE_URL`, the hosted API when it
+ * is not set. An empty variable counts as unset, except `PIPELEX_BASE_URL`: an empty one, such as
+ * an unfilled CI secret, reaches the SDK, which refuses it, rather than send the key to the hosted
+ * API by default. No `.env` file is read: a command started through `npx` from wherever the person
+ * stands would otherwise pick a credential from whichever file it found there.
+ */
+import { DEFAULT_API_BASE_URL, PipelexApiClient, RequestArgumentError, SDK_VERSION, } from "../index.js";
+import { usageError } from "./io.js";
+export const API_KEY_VARIABLE = "PIPELEX_API_KEY";
+export const BASE_URL_VARIABLE = "PIPELEX_BASE_URL";
+/**
+ * The poll interval in milliseconds, for tests only: the recorded case table sets it to `0`, so
+ * that a run answered "still running" is polled again at once. A person has no reason to set it;
+ * unset, the SDK's own interval applies. The Python command reads the same variable.
+ */
+export const POLL_INTERVAL_VARIABLE = "PIPELEX_SDK_POLL_INTERVAL_MS";
+/** The name the command gives itself in the `User-Agent` of every request, before the SDK's own. */
+export const CLIENT_APP_NAME = "pipelex-sdk-cli";
+function variable(io, name) {
+    const value = io.env[name];
+    return value === undefined || value === "" ? undefined : value;
+}
+/**
+ * The test-only poll interval, or `undefined` for the SDK's own.
+ *
+ * @throws {CommandError} A usage error when it is set to anything but a whole number.
+ */
+export function readPollInterval(io) {
+    const value = variable(io, POLL_INTERVAL_VARIABLE);
+    if (value === undefined)
+        return undefined;
+    if (!/^[0-9]+$/.test(value)) {
+        throw usageError(`${POLL_INTERVAL_VARIABLE} must be a whole number of milliseconds.`);
+    }
+    return Number(value);
+}
+/**
+ * The client every request goes through, built from the key and the base URL.
+ *
+ * @throws {CommandError} A usage error when the key is missing or the base URL is refused. The
+ *   refusal never quotes the key, and the SDK's refusal of a base URL never quotes the parts of it
+ *   that can carry a secret.
+ */
+export function makeClient(io) {
+    const apiKey = variable(io, API_KEY_VARIABLE);
+    if (apiKey === undefined) {
+        throw usageError(`${API_KEY_VARIABLE} is not set.`, [
+            `Get a key at https://app.pipelex.com and export it: export ${API_KEY_VARIABLE}=<your key>`,
+            "This command reads no .env file; to load one into the shell, run: set -a; . ./.env; set +a",
+        ]);
+    }
+    try {
+        return new PipelexApiClient({
+            apiKey,
+            // Absent, not empty, means the hosted API: the SDK refuses an empty base URL on purpose, so
+            // an unfilled CI secret never sends the key to the hosted API by default.
+            baseUrl: io.env[BASE_URL_VARIABLE] ?? DEFAULT_API_BASE_URL,
+            appInfo: { name: CLIENT_APP_NAME, version: SDK_VERSION },
+        });
+    }
+    catch (error) {
+        if (error instanceof RequestArgumentError) {
+            throw usageError(`${BASE_URL_VARIABLE} is refused.`, [`Reason: ${error.message}`]);
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=environment.js.map

package/dist/cli/environment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.js","sourceRoot":"","sources":["../../src/cli/environment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,oBAAoB,EACpB,WAAW,GACZ,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAGrC,MAAM,CAAC,MAAM,gBAAgB,GAAG,iBAAiB,CAAC;AAClD,MAAM,CAAC,MAAM,iBAAiB,GAAG,kBAAkB,CAAC;AAEpD;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,8BAA8B,CAAC;AAErE,oGAAoG;AACpG,MAAM,CAAC,MAAM,eAAe,GAAG,iBAAiB,CAAC;AAEjD,SAAS,QAAQ,CAAC,EAAa,EAAE,IAAY;IAC3C,MAAM,KAAK,GAAG,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC3B,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC;AACjE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,EAAa;IAC5C,MAAM,KAAK,GAAG,QAAQ,CAAC,EAAE,EAAE,sBAAsB,CAAC,CAAC;IACnD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC1C,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,UAAU,CAAC,GAAG,sBAAsB,0CAA0C,CAAC,CAAC;IACxF,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,EAAa;IACtC,MAAM,MAAM,GAAG,QAAQ,CAAC,EAAE,EAAE,gBAAgB,CAAC,CAAC;IAC9C,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,UAAU,CAAC,GAAG,gBAAgB,cAAc,EAAE;YAClD,8DAA8D,gBAAgB,aAAa;YAC3F,4FAA4F;SAC7F,CAAC,CAAC;IACL,CAAC;IACD,IAAI,CAAC;QACH,OAAO,IAAI,gBAAgB,CAAC;YAC1B,MAAM;YACN,4FAA4F;YAC5F,0EAA0E;YAC1E,OAAO,EAAE,EAAE,CAAC,GAAG,CAAC,iBAAiB,CAAC,IAAI,oBAAoB;YAC1D,OAAO,EAAE,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,WAAW,EAAE;SACzD,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,oBAAoB,EAAE,CAAC;YAC1C,MAAM,UAAU,CAAC,GAAG,iBAAiB,cAAc,EAAE,CAAC,WAAW,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QACrF,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/cli/help.d.ts

@@ -0,0 +1,4 @@
+/** The command's help texts, printed on stdout by `--help`. */
+export declare const MAIN_HELP = "pipelex-sdk: run an MTHDS method on the Pipelex API, with nothing to install.\n\nUsage:\n  pipelex-sdk run --method <method> [--pipe <domain.pipe_code>] [--inputs <file> | --inputs-template]\n  pipelex-sdk script --method <address | catalog id> [--pipe <domain.pipe_code>] [--name <name>] [--dir <dir>]\n  pipelex-sdk --version\n  pipelex-sdk <command> --help\n\nCommands:\n  run      Run a method and print its main output as JSON on stdout.\n  script   Write a shell script that runs one method with this SDK's version pinned.\n\nA method is a published address, github.com/<owner>/<repo>[/<package>][@<tag>], a catalog\nid, mt_..., or, for run only, a .mthds file or a bundle directory.\n\nThe API key is read from PIPELEX_API_KEY, and the API's address from PIPELEX_BASE_URL\n(https://api.pipelex.com when unset). No .env file is read.\n\nExit codes: 0 done, 1 the run failed or the API refused it, 2 a usage error, 130 interrupted.\n";
+export declare const RUN_HELP = "Usage: pipelex-sdk run --method <method> [--pipe <domain.pipe_code>] [--inputs <file> | --inputs-template]\n\nRun a method on the Pipelex API, wait for it however long it takes, and print its main\noutput as indented JSON on stdout. The run id, each uploaded file and every error go to\nstderr. Ctrl-C stops waiting; the run keeps going on the server.\n\nOptions:\n  --method <method>          A published address (github.com/<owner>/<repo>[/<package>][@<tag>]),\n                             a catalog id (mt_...), or a path to a .mthds file or a bundle directory.\n  --pipe <domain.pipe_code>  The pipe to run, by its qualified ref. Default: the method's main pipe.\n  --inputs <file>            The inputs, a JSON object with one entry per input; - reads stdin.\n                             A local path or a data: URL at a file input is uploaded first.\n  --inputs-template          Print the inputs template, the object --inputs takes, and run nothing.\n  -h, --help                 Show this help.\n\nNeeds PIPELEX_API_KEY in the environment.\n";
+export declare const SCRIPT_HELP = "Usage: pipelex-sdk script --method <address | catalog id> [--pipe <domain.pipe_code>] [--name <name>] [--dir <dir>]\n\nCheck a method with the API, then write an executable shell script that runs it through\nthis SDK, its version pinned. The script passes its own arguments on to run:\n./<name> --inputs inputs.json, or ./<name> --inputs-template. It never overwrites a file.\n\nOptions:\n  --method <method>          A published address (github.com/<owner>/<repo>[/<package>][@<tag>])\n                             or a catalog id (mt_...). A local bundle is refused.\n  --pipe <domain.pipe_code>  The pipe the script runs. Default: the method's main pipe.\n  --name <name>              The script's file name. Default: the address's last segment, or the\n                             catalog method's name in kebab-case.\n  --dir <dir>                Where to write it. Default: the current directory.\n  -h, --help                 Show this help.\n\nNeeds PIPELEX_API_KEY in the environment. The script needs a POSIX shell.\n";

package/dist/cli/help.js

@@ -0,0 +1,56 @@
+/** The command's help texts, printed on stdout by `--help`. */
+export const MAIN_HELP = `pipelex-sdk: run an MTHDS method on the Pipelex API, with nothing to install.
+
+Usage:
+  pipelex-sdk run --method <method> [--pipe <domain.pipe_code>] [--inputs <file> | --inputs-template]
+  pipelex-sdk script --method <address | catalog id> [--pipe <domain.pipe_code>] [--name <name>] [--dir <dir>]
+  pipelex-sdk --version
+  pipelex-sdk <command> --help
+
+Commands:
+  run      Run a method and print its main output as JSON on stdout.
+  script   Write a shell script that runs one method with this SDK's version pinned.
+
+A method is a published address, github.com/<owner>/<repo>[/<package>][@<tag>], a catalog
+id, mt_..., or, for run only, a .mthds file or a bundle directory.
+
+The API key is read from PIPELEX_API_KEY, and the API's address from PIPELEX_BASE_URL
+(https://api.pipelex.com when unset). No .env file is read.
+
+Exit codes: 0 done, 1 the run failed or the API refused it, 2 a usage error, 130 interrupted.
+`;
+export const RUN_HELP = `Usage: pipelex-sdk run --method <method> [--pipe <domain.pipe_code>] [--inputs <file> | --inputs-template]
+
+Run a method on the Pipelex API, wait for it however long it takes, and print its main
+output as indented JSON on stdout. The run id, each uploaded file and every error go to
+stderr. Ctrl-C stops waiting; the run keeps going on the server.
+
+Options:
+  --method <method>          A published address (github.com/<owner>/<repo>[/<package>][@<tag>]),
+                             a catalog id (mt_...), or a path to a .mthds file or a bundle directory.
+  --pipe <domain.pipe_code>  The pipe to run, by its qualified ref. Default: the method's main pipe.
+  --inputs <file>            The inputs, a JSON object with one entry per input; - reads stdin.
+                             A local path or a data: URL at a file input is uploaded first.
+  --inputs-template          Print the inputs template, the object --inputs takes, and run nothing.
+  -h, --help                 Show this help.
+
+Needs PIPELEX_API_KEY in the environment.
+`;
+export const SCRIPT_HELP = `Usage: pipelex-sdk script --method <address | catalog id> [--pipe <domain.pipe_code>] [--name <name>] [--dir <dir>]
+
+Check a method with the API, then write an executable shell script that runs it through
+this SDK, its version pinned. The script passes its own arguments on to run:
+./<name> --inputs inputs.json, or ./<name> --inputs-template. It never overwrites a file.
+
+Options:
+  --method <method>          A published address (github.com/<owner>/<repo>[/<package>][@<tag>])
+                             or a catalog id (mt_...). A local bundle is refused.
+  --pipe <domain.pipe_code>  The pipe the script runs. Default: the method's main pipe.
+  --name <name>              The script's file name. Default: the address's last segment, or the
+                             catalog method's name in kebab-case.
+  --dir <dir>                Where to write it. Default: the current directory.
+  -h, --help                 Show this help.
+
+Needs PIPELEX_API_KEY in the environment. The script needs a POSIX shell.
+`;
+//# sourceMappingURL=help.js.map

package/dist/cli/help.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../../src/cli/help.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAE/D,MAAM,CAAC,MAAM,SAAS,GAAG;;;;;;;;;;;;;;;;;;;CAmBxB,CAAC;AAEF,MAAM,CAAC,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;CAgBvB,CAAC;AAEF,MAAM,CAAC,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;CAgB1B,CAAC"}

package/dist/cli/inputs.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The inputs `--inputs` names: a JSON object, one entry per input, read from a file or, for `-`,
+ * from stdin. It is the shape `mthds run --inputs` and `cli-python`'s `--inputs` take, and the
+ * shape `--inputs-template` prints.
+ */
+import type { CommandIO } from "./io.js";
+/**
+ * Read and parse the inputs. A relative path resolves against the current directory.
+ *
+ * @throws {CommandError} A usage error for an unreadable file or stdin, text that is not UTF-8 or
+ *   not JSON, and JSON that is not an object.
+ */
+export declare function readInputs(source: string, io: CommandIO): Promise<Record<string, unknown>>;

package/dist/cli/inputs.js

@@ -0,0 +1,70 @@
+/**
+ * The inputs `--inputs` names: a JSON object, one entry per input, read from a file or, for `-`,
+ * from stdin. It is the shape `mthds run --inputs` and `cli-python`'s `--inputs` take, and the
+ * shape `--inputs-template` prints.
+ */
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { systemReason } from "./bundle.js";
+import { untilInterrupted, usageError } from "./io.js";
+// A leading byte-order mark is dropped, as RFC 8259 lets a JSON reader do: Windows PowerShell 5.1
+// writes one with `Out-File -Encoding utf8`. A bundle's mark is kept, since it is sent as written.
+const UTF8 = new TextDecoder("utf-8", { fatal: true });
+/**
+ * Read and parse the inputs. A relative path resolves against the current directory.
+ *
+ * @throws {CommandError} A usage error for an unreadable file or stdin, text that is not UTF-8 or
+ *   not JSON, and JSON that is not an object.
+ */
+export async function readInputs(source, io) {
+    const label = source === "-" ? "stdin" : `the inputs file "${source}"`;
+    const read = source === "-" ? () => io.readStdin() : () => readFile(resolve(source));
+    // Raced with the interrupt: stdin, a named pipe or a file on a stalled mount can keep the read
+    // waiting.
+    const bytes = await untilInterrupted(async () => {
+        try {
+            return await read();
+        }
+        catch (error) {
+            throw usageError(`cannot read ${label}.`, [`Reason: ${systemReason(error)}`]);
+        }
+    }, io.interrupt);
+    let text;
+    try {
+        text = UTF8.decode(bytes);
+    }
+    catch {
+        throw usageError(`${label} is not UTF-8 text.`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        throw usageError(`${label} is not valid JSON.`, [
+            `Reason: ${error instanceof Error ? error.message : String(error)}`,
+        ]);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw usageError(`${label} must hold a JSON object, one entry per input, and holds ${jsonKind(parsed)}.`, ["Run with --inputs-template to see the object this method takes."]);
+    }
+    return parsed;
+}
+/** What a JSON value is, said the way the refusal says it. */
+function jsonKind(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "an array";
+    switch (typeof value) {
+        case "string":
+            return "a string";
+        case "number":
+            return "a number";
+        case "boolean":
+            return "a boolean";
+        default:
+            return "not an object";
+    }
+}
+//# sourceMappingURL=inputs.js.map

package/dist/cli/inputs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inputs.js","sourceRoot":"","sources":["../../src/cli/inputs.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAGvD,kGAAkG;AAClG,mGAAmG;AACnG,MAAM,IAAI,GAAG,IAAI,WAAW,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,MAAc,EAAE,EAAa;IAC5D,MAAM,KAAK,GAAG,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,oBAAoB,MAAM,GAAG,CAAC;IACvE,MAAM,IAAI,GAAG,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IACrF,+FAA+F;IAC/F,WAAW;IACX,MAAM,KAAK,GAAG,MAAM,gBAAgB,CAAC,KAAK,IAAI,EAAE;QAC9C,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,EAAE,CAAC;QACtB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,UAAU,CAAC,eAAe,KAAK,GAAG,EAAE,CAAC,WAAW,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;QAChF,CAAC;IACH,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC;IACjB,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,UAAU,CAAC,GAAG,KAAK,qBAAqB,CAAC,CAAC;IAClD,CAAC;IACD,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,UAAU,CAAC,GAAG,KAAK,qBAAqB,EAAE;YAC9C,WAAW,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE;SACpE,CAAC,CAAC;IACL,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3E,MAAM,UAAU,CACd,GAAG,KAAK,4DAA4D,QAAQ,CAAC,MAAM,CAAC,GAAG,EACvF,CAAC,iEAAiE,CAAC,CACpE,CAAC;IACJ,CAAC;IACD,OAAO,MAAiC,CAAC;AAC3C,CAAC;AAED,8DAA8D;AAC9D,SAAS,QAAQ,CAAC,KAAc;IAC9B,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAClC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,UAAU,CAAC;IAC5C,QAAQ,OAAO,KAAK,EAAE,CAAC;QACrB,KAAK,QAAQ;YACX,OAAO,UAAU,CAAC;QACpB,KAAK,QAAQ;YACX,OAAO,UAAU,CAAC;QACpB,KAAK,SAAS;YACZ,OAAO,WAAW,CAAC;QACrB;YACE,OAAO,eAAe,CAAC;IAC3B,CAAC;AACH,CAAC"}

package/dist/cli/io.d.ts

@@ -0,0 +1,79 @@
+/**
+ * What the `pipelex-sdk` command reads from and writes to, and the ways it stops early.
+ *
+ * The command never touches `process` directly, apart from the current directory that relative
+ * paths resolve against: `src/cli.ts`, the executable, hands it the real streams, environment and
+ * Ctrl-C, and the test suite hands it its own. That is what lets one recorded case table drive
+ * the command in-process, in this SDK and in its Python twin (`docs/cli.md`).
+ */
+/** The command's world: its environment, its three streams and the interrupt. */
+export interface CommandIO {
+    /**
+     * The environment the command reads: `PIPELEX_API_KEY`, `PIPELEX_BASE_URL` and the test-only
+     * `PIPELEX_SDK_POLL_INTERVAL_MS`. Nothing else is read from it, and no `.env` file is read.
+     */
+    readonly env: Readonly<Record<string, string | undefined>>;
+    /**
+     * All of stdin, as bytes. Read only for `--inputs -`. It rejects with the system's error when
+     * stdin cannot be read; a process started with stdin closed reads it as empty, since Node opens
+     * the null device on a standard stream it starts without.
+     */
+    readStdin(): Promise<Uint8Array>;
+    /** Write to stdout, which carries the result and nothing else. */
+    writeStdout(text: string): void;
+    /** Write to stderr, which carries everything that is not the result. */
+    writeStderr(text: string): void;
+    /** Aborted when the person interrupts the command (Ctrl-C). */
+    readonly interrupt: AbortSignal;
+}
+/** The command's exit codes (`docs/cli.md`): a script reads stdout, and these are presentation. */
+export declare const EXIT_OK = 0;
+export declare const EXIT_FAILED = 1;
+export declare const EXIT_USAGE = 2;
+export declare const EXIT_INTERRUPTED = 130;
+/**
+ * A failure the command words itself: a usage error (exit code 2), a refusal it reads off an
+ * answer (exit code 1), or an interrupt (exit code 130). Its message is the sentence after
+ * `Error: `, or the whole first line when `bare`, as an interrupt's is; `details` are the lines
+ * printed under it, as they are.
+ */
+export declare class CommandError extends Error {
+    readonly exitCode: number;
+    readonly details: readonly string[];
+    readonly bare: boolean;
+    constructor(message: string, options: {
+        exitCode: number;
+        details?: readonly string[];
+        bare?: boolean;
+    });
+}
+/** A usage error: something the person can fix on the command line or in the environment. */
+export declare function usageError(message: string, details?: readonly string[]): CommandError;
+/** The person interrupted the command while it was waiting on something. */
+export declare class Interrupted extends Error {
+    constructor();
+}
+/**
+ * Start a step and wait for it, unless the person interrupts first, which rejects with
+ * {@link Interrupted}.
+ *
+ * The step is given as a function, so that an interrupt that has already landed starts nothing:
+ * a request is never sent once the person has asked to stop, and what the command then says ("No
+ * run was started") stays true. An interrupt that lands while the step starts is caught as soon
+ * as it returns.
+ *
+ * Several of the SDK's requests take no abort signal (the input preparation, the start request,
+ * the blocking execute), so the command stops waiting for them rather than cancelling them; the
+ * executable exits right after it has said so. The promise left behind is given a handler, so its
+ * later failure is never reported as unhandled.
+ */
+export declare function untilInterrupted<T>(start: () => Promise<T>, signal: AbortSignal): Promise<T>;
+/** Write each line to stderr, each ended by a newline. */
+export declare function writeLines(io: CommandIO, lines: readonly string[]): void;
+/**
+ * Let a reader of one of the process's output streams stop early: `| head` closes the pipe, and
+ * the next write fails with `EPIPE`, which, unhandled, would end the process mid-run, a run it
+ * started included. There is nothing left to tell that reader, so the error is dropped; any other
+ * error on the stream is thrown as it would have been.
+ */
+export declare function ignoreClosedPipe(stream: NodeJS.EventEmitter): void;

package/dist/cli/io.js

@@ -0,0 +1,96 @@
+/**
+ * What the `pipelex-sdk` command reads from and writes to, and the ways it stops early.
+ *
+ * The command never touches `process` directly, apart from the current directory that relative
+ * paths resolve against: `src/cli.ts`, the executable, hands it the real streams, environment and
+ * Ctrl-C, and the test suite hands it its own. That is what lets one recorded case table drive
+ * the command in-process, in this SDK and in its Python twin (`docs/cli.md`).
+ */
+/** The command's exit codes (`docs/cli.md`): a script reads stdout, and these are presentation. */
+export const EXIT_OK = 0;
+export const EXIT_FAILED = 1;
+export const EXIT_USAGE = 2;
+export const EXIT_INTERRUPTED = 130;
+/**
+ * A failure the command words itself: a usage error (exit code 2), a refusal it reads off an
+ * answer (exit code 1), or an interrupt (exit code 130). Its message is the sentence after
+ * `Error: `, or the whole first line when `bare`, as an interrupt's is; `details` are the lines
+ * printed under it, as they are.
+ */
+export class CommandError extends Error {
+    exitCode;
+    details;
+    bare;
+    constructor(message, options) {
+        super(message);
+        this.name = "CommandError";
+        this.exitCode = options.exitCode;
+        this.details = options.details ?? [];
+        this.bare = options.bare ?? false;
+    }
+}
+/** A usage error: something the person can fix on the command line or in the environment. */
+export function usageError(message, details = []) {
+    return new CommandError(message, { exitCode: EXIT_USAGE, details });
+}
+/** The person interrupted the command while it was waiting on something. */
+export class Interrupted extends Error {
+    constructor() {
+        super("Interrupted.");
+        this.name = "Interrupted";
+    }
+}
+/**
+ * Start a step and wait for it, unless the person interrupts first, which rejects with
+ * {@link Interrupted}.
+ *
+ * The step is given as a function, so that an interrupt that has already landed starts nothing:
+ * a request is never sent once the person has asked to stop, and what the command then says ("No
+ * run was started") stays true. An interrupt that lands while the step starts is caught as soon
+ * as it returns.
+ *
+ * Several of the SDK's requests take no abort signal (the input preparation, the start request,
+ * the blocking execute), so the command stops waiting for them rather than cancelling them; the
+ * executable exits right after it has said so. The promise left behind is given a handler, so its
+ * later failure is never reported as unhandled.
+ */
+export function untilInterrupted(start, signal) {
+    if (signal.aborted)
+        return Promise.reject(new Interrupted());
+    const promise = start();
+    if (signal.aborted) {
+        promise.catch(() => undefined);
+        return Promise.reject(new Interrupted());
+    }
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            promise.catch(() => undefined);
+            reject(new Interrupted());
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        promise.then((value) => {
+            signal.removeEventListener("abort", onAbort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener("abort", onAbort);
+            reject(error);
+        });
+    });
+}
+/** Write each line to stderr, each ended by a newline. */
+export function writeLines(io, lines) {
+    io.writeStderr(lines.map((line) => `${line}\n`).join(""));
+}
+/**
+ * Let a reader of one of the process's output streams stop early: `| head` closes the pipe, and
+ * the next write fails with `EPIPE`, which, unhandled, would end the process mid-run, a run it
+ * started included. There is nothing left to tell that reader, so the error is dropped; any other
+ * error on the stream is thrown as it would have been.
+ */
+export function ignoreClosedPipe(stream) {
+    stream.on("error", (error) => {
+        if (error.code !== "EPIPE")
+            throw error;
+    });
+}
+//# sourceMappingURL=io.js.map

package/dist/cli/io.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"io.js","sourceRoot":"","sources":["../../src/cli/io.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAuBH,mGAAmG;AACnG,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,CAAC;AACzB,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC;AAC7B,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC;AAC5B,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAEpC;;;;;GAKG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IACrB,QAAQ,CAAS;IACjB,OAAO,CAAoB;IAC3B,IAAI,CAAU;IAE9B,YACE,OAAe,EACf,OAA0E;QAE1E,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;QACrC,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,KAAK,CAAC;IACpC,CAAC;CACF;AAED,6FAA6F;AAC7F,MAAM,UAAU,UAAU,CAAC,OAAe,EAAE,UAA6B,EAAE;IACzE,OAAO,IAAI,YAAY,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,CAAC;AACtE,CAAC;AAED,4EAA4E;AAC5E,MAAM,OAAO,WAAY,SAAQ,KAAK;IACpC;QACE,KAAK,CAAC,cAAc,CAAC,CAAC;QACtB,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,gBAAgB,CAAI,KAAuB,EAAE,MAAmB;IAC9E,IAAI,MAAM,CAAC,OAAO;QAAE,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,WAAW,EAAE,CAAC,CAAC;IAC7D,MAAM,OAAO,GAAG,KAAK,EAAE,CAAC;IACxB,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC/B,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,WAAW,EAAE,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACxC,MAAM,OAAO,GAAG,GAAS,EAAE;YACzB,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;YAC/B,MAAM,CAAC,IAAI,WAAW,EAAE,CAAC,CAAC;QAC5B,CAAC,CAAC;QACF,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1D,OAAO,CAAC,IAAI,CACV,CAAC,KAAK,EAAE,EAAE;YACR,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC7C,OAAO,CAAC,KAAK,CAAC,CAAC;QACjB,CAAC,EACD,CAAC,KAAc,EAAE,EAAE;YACjB,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC7C,MAAM,CAAC,KAAK,CAAC,CAAC;QAChB,CAAC,CACF,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,UAAU,CAAC,EAAa,EAAE,KAAwB;IAChE,EAAE,CAAC,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;AAC5D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAA2B;IAC1D,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAA4B,EAAE,EAAE;QAClD,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO;YAAE,MAAM,KAAK,CAAC;IAC1C,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/cli/main.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The `pipelex-sdk` command: `run` runs a method and prints its main output, `script` writes the
+ * per-method shell script. `docs/cli.md` describes both, and `tests/fixtures/cli-cases.json`
+ * records what each prints for every case, which the Python twin answers too.
+ *
+ * Nothing in the SDK imports this module or its siblings, and the package entry does not export
+ * them (`.dependency-cruiser.cjs`): the command sits at the top of the dependency graph, and reaches
+ * the SDK only through its public barrel, as any other caller would.
+ */
+import type { CommandIO } from "./io.js";
+export type { CommandIO } from "./io.js";
+/**
+ * Run the command on `argv`, the arguments after the command's own name, and return its exit
+ * code: 0 when it did what it was asked, 1 when the run failed or the API refused it, 2 for a
+ * usage error and 130 when interrupted. Every failure is printed on stderr before it returns; it
+ * never throws.
+ */
+export declare function runCommand(argv: readonly string[], io: CommandIO): Promise<number>;