@pipelex/sdk 0.32.0 → 0.34.0

package/dist/cli/main.js

@@ -0,0 +1,58 @@
+/**
+ * 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 { SDK_VERSION } from "../index.js";
+import { MAIN_HELP } from "./help.js";
+import { EXIT_OK, usageError, writeLines } from "./io.js";
+import { presentError } from "./present.js";
+import { runCommandRun } from "./run.js";
+import { runCommandScript } from "./script.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 async function runCommand(argv, io) {
+    try {
+        const [command, ...rest] = argv;
+        switch (command) {
+            case undefined:
+                throw usageError("name a command: run or script.", [
+                    "Run 'pipelex-sdk --help' to see what each does.",
+                ]);
+            case "--help":
+            case "-h":
+                // The help wins whatever follows it, as it does in a subcommand.
+                io.writeStdout(MAIN_HELP);
+                return EXIT_OK;
+            case "--version":
+                // Unlike the help, the version is not printed over a command line it does not answer.
+                if (rest.length > 0) {
+                    throw usageError(`unexpected argument "${rest[0]}" after --version.`, [
+                        "Run 'pipelex-sdk --version' alone to print the version.",
+                    ]);
+                }
+                io.writeStdout(`${SDK_VERSION}\n`);
+                return EXIT_OK;
+            case "run":
+                return await runCommandRun(rest, io);
+            case "script":
+                return await runCommandScript(rest, io);
+            default:
+                throw usageError(command.startsWith("-") ? `unknown option ${command}.` : `unknown command "${command}".`, ["The commands are run and script. Run 'pipelex-sdk --help' to see what each does."]);
+        }
+    }
+    catch (error) {
+        const presented = presentError(error);
+        writeLines(io, presented.lines);
+        return presented.exitCode;
+    }
+}
+//# sourceMappingURL=main.js.map

package/dist/cli/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1D,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAI/C;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAuB,EAAE,EAAa;IACrE,IAAI,CAAC;QACH,MAAM,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;QAChC,QAAQ,OAAO,EAAE,CAAC;YAChB,KAAK,SAAS;gBACZ,MAAM,UAAU,CAAC,gCAAgC,EAAE;oBACjD,iDAAiD;iBAClD,CAAC,CAAC;YACL,KAAK,QAAQ,CAAC;YACd,KAAK,IAAI;gBACP,iEAAiE;gBACjE,EAAE,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;gBAC1B,OAAO,OAAO,CAAC;YACjB,KAAK,WAAW;gBACd,sFAAsF;gBACtF,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBACpB,MAAM,UAAU,CAAC,wBAAwB,IAAI,CAAC,CAAC,CAAC,oBAAoB,EAAE;wBACpE,yDAAyD;qBAC1D,CAAC,CAAC;gBACL,CAAC;gBACD,EAAE,CAAC,WAAW,CAAC,GAAG,WAAW,IAAI,CAAC,CAAC;gBACnC,OAAO,OAAO,CAAC;YACjB,KAAK,KAAK;gBACR,OAAO,MAAM,aAAa,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YACvC,KAAK,QAAQ;gBACX,OAAO,MAAM,gBAAgB,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YAC1C;gBACE,MAAM,UAAU,CACd,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,kBAAkB,OAAO,GAAG,CAAC,CAAC,CAAC,oBAAoB,OAAO,IAAI,EACxF,CAAC,kFAAkF,CAAC,CACrF,CAAC;QACN,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,SAAS,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;QACtC,UAAU,CAAC,EAAE,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC;QAChC,OAAO,SAAS,CAAC,QAAQ,CAAC;IAC5B,CAAC;AACH,CAAC"}

package/dist/cli/method.d.ts

@@ -0,0 +1,56 @@
+/**
+ * How the command names a method and a pipe: the forms of `--method`, the qualified form of
+ * `--pipe`, and the names and quoting `script` derives from them.
+ */
+/** The prefix of a published method's address. */
+export declare const ADDRESS_PREFIX = "github.com/";
+/** The prefix of a stored method's catalog id. */
+export declare const CATALOG_ID_PREFIX = "mt_";
+/** A `--method` value, told apart by its shape alone. */
+export type MethodSelector = {
+    readonly kind: "address";
+    readonly methodRef: string;
+} | {
+    readonly kind: "catalog";
+    readonly methodId: string;
+} | {
+    readonly kind: "path";
+    readonly path: string;
+};
+/**
+ * Tell a `--method` value's form by its shape: `mt_…` is a catalog id, `github.com/…` an address,
+ * and anything else a path to a `.mthds` file or a bundle directory. A file or directory that
+ * happens to be named `mt_…` is reached as `./mt_…`, so that what a value names never depends on
+ * what the current directory holds.
+ *
+ * @throws {CommandError} A usage error for an `mt_…` value holding a character no catalog id
+ *   holds (a letter, a digit, `_` or `-`), such as `mt_review.mthds`, which is a path written
+ *   without its `./`.
+ */
+export declare function classifyMethod(value: string): MethodSelector;
+/**
+ * Hold `--pipe` to the qualified ref, `domain.pipe_code`, which the input preparation and the
+ * pipe I/O route require. A bare code is refused, and so is an `alias->domain.pipe_code` ref,
+ * which names a dependency package's pipe rather than one of the method's own.
+ */
+export declare function checkPipeRef(value: string): void;
+/** Whether a value holds a control character, which no line of a written script may carry. */
+export declare function hasControlCharacter(value: string): boolean;
+/**
+ * An address's tag, the text after its last `@`, or `undefined` for an address with none. An
+ * empty tag counts as none.
+ */
+export declare function addressTag(methodRef: string): string | undefined;
+/** An address's last path segment, without its tag: the default name of the script it gets. */
+export declare function addressName(methodRef: string): string;
+/**
+ * A catalog method's name as a script's file name: decomposed (NFKD), stripped of its combining
+ * marks, lowercased, every run of characters outside `a-z` and `0-9` turned into one `-`, and
+ * trimmed of `-` at both ends. `Résumé Review (v2)` becomes `resume-review-v2`; a name of no
+ * letter or digit becomes the empty string.
+ */
+export declare function kebabCase(text: string): string;
+/** Why a script's file name cannot be used, or `undefined` when it can. */
+export declare function scriptNameProblem(name: string): string | undefined;
+/** A value as one single-quoted shell word, an inner `'` spelled `'\''`. */
+export declare function shellQuote(value: string): string;

package/dist/cli/method.js

@@ -0,0 +1,108 @@
+/**
+ * How the command names a method and a pipe: the forms of `--method`, the qualified form of
+ * `--pipe`, and the names and quoting `script` derives from them.
+ */
+import { usageError } from "./io.js";
+/** The prefix of a published method's address. */
+export const ADDRESS_PREFIX = "github.com/";
+/** The prefix of a stored method's catalog id. */
+export const CATALOG_ID_PREFIX = "mt_";
+/** The characters a catalog id is made of, which the API's run route accepts and no other. */
+const CATALOG_ID_SHAPE = /^[A-Za-z0-9_-]+$/;
+/**
+ * Tell a `--method` value's form by its shape: `mt_…` is a catalog id, `github.com/…` an address,
+ * and anything else a path to a `.mthds` file or a bundle directory. A file or directory that
+ * happens to be named `mt_…` is reached as `./mt_…`, so that what a value names never depends on
+ * what the current directory holds.
+ *
+ * @throws {CommandError} A usage error for an `mt_…` value holding a character no catalog id
+ *   holds (a letter, a digit, `_` or `-`), such as `mt_review.mthds`, which is a path written
+ *   without its `./`.
+ */
+export function classifyMethod(value) {
+    if (value.startsWith(CATALOG_ID_PREFIX)) {
+        if (!CATALOG_ID_SHAPE.test(value)) {
+            throw usageError(`--method "${value}" is not a catalog id: a catalog id holds only letters, digits, _ and -.`, [`To name a local file or directory whose name starts with mt_, write it as ./${value}.`]);
+        }
+        return { kind: "catalog", methodId: value };
+    }
+    if (value.startsWith(ADDRESS_PREFIX))
+        return { kind: "address", methodRef: value };
+    return { kind: "path", path: value };
+}
+/**
+ * Hold `--pipe` to the qualified ref, `domain.pipe_code`, which the input preparation and the
+ * pipe I/O route require. A bare code is refused, and so is an `alias->domain.pipe_code` ref,
+ * which names a dependency package's pipe rather than one of the method's own.
+ */
+export function checkPipeRef(value) {
+    if (value.includes("->")) {
+        throw usageError(`--pipe "${value}" names a dependency package's pipe; name one of the method's own pipes as domain.pipe_code.`);
+    }
+    if (!value.includes(".")) {
+        throw usageError(`--pipe takes a pipe's qualified ref, domain.pipe_code, and "${value}" has no domain.`, [`Write it as <domain>.${value}, the domain being the one its .mthds file declares.`]);
+    }
+}
+/** Whether a value holds a control character, which no line of a written script may carry. */
+export function hasControlCharacter(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code < 0x20 || code === 0x7f)
+            return true;
+    }
+    return false;
+}
+/**
+ * An address's tag, the text after its last `@`, or `undefined` for an address with none. An
+ * empty tag counts as none.
+ */
+export function addressTag(methodRef) {
+    const at = methodRef.lastIndexOf("@");
+    if (at < 0)
+        return undefined;
+    const tag = methodRef.slice(at + 1);
+    return tag === "" ? undefined : tag;
+}
+/** An address's last path segment, without its tag: the default name of the script it gets. */
+export function addressName(methodRef) {
+    const at = methodRef.lastIndexOf("@");
+    const base = at < 0 ? methodRef : methodRef.slice(0, at);
+    const segments = base.split("/").filter((segment) => segment !== "");
+    return segments[segments.length - 1] ?? "";
+}
+/**
+ * A catalog method's name as a script's file name: decomposed (NFKD), stripped of its combining
+ * marks, lowercased, every run of characters outside `a-z` and `0-9` turned into one `-`, and
+ * trimmed of `-` at both ends. `Résumé Review (v2)` becomes `resume-review-v2`; a name of no
+ * letter or digit becomes the empty string.
+ */
+export function kebabCase(text) {
+    return text
+        .normalize("NFKD")
+        .replace(/\p{M}/gu, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+/** Why a script's file name cannot be used, or `undefined` when it can. */
+export function scriptNameProblem(name) {
+    if (name === "")
+        return "is empty";
+    if (name === "." || name === "..")
+        return `"${name}" names a directory`;
+    if (name.includes("/"))
+        return `"${name}" holds a /, and --dir is where the script goes`;
+    // On every platform, so both SDKs refuse the same names: Windows reads a \ as a /, and
+    // `..\outside` would leave --dir there.
+    if (name.includes("\\")) {
+        return `"${name}" holds a \\, which Windows reads as a /, and --dir is where the script goes`;
+    }
+    if (hasControlCharacter(name))
+        return "holds a control character";
+    return undefined;
+}
+/** A value as one single-quoted shell word, an inner `'` spelled `'\''`. */
+export function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+//# sourceMappingURL=method.js.map

package/dist/cli/method.js.map

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

package/dist/cli/present.d.ts

@@ -0,0 +1,43 @@
+/**
+ * What the command prints: a finished run's result on stdout, and every failure on stderr.
+ *
+ * A failure is worded by the command from the error's typed fields, never from an SDK message
+ * whose wording is the SDK's own, wherever the fields carry what a person needs: the API's reason,
+ * the next step it advises and the request id support asks for. That keeps the two commands, this
+ * one and its Python twin, saying the same thing for the same answer, which is what the recorded
+ * case table holds them to.
+ */
+import type { ValidationErrorItem } from "../index.js";
+import type { CommandIO } from "./io.js";
+/** A failure as the command prints it: its lines, and the exit code it ends with. */
+export interface PresentedError {
+    readonly lines: readonly string[];
+    readonly exitCode: number;
+}
+/** Word any failure for stderr and choose its exit code. */
+export declare function presentError(error: unknown): PresentedError;
+/** The first line of a method that does not load, after `Error: `. */
+export declare const METHOD_DOES_NOT_LOAD_SENTENCE = "the method does not load.";
+/**
+ * The lines under "the method does not load": one per validation item that carries a string
+ * `category` and `message`, the rule the SDK reads a failed load's items by, and when there is
+ * none, the answer's own message.
+ */
+export declare function loadFailureLines(items: unknown, message: unknown): string[];
+/** One validation error, as an indented line naming its file when it has one. */
+export declare function validationLine(item: Pick<ValidationErrorItem, "message"> & {
+    source?: unknown;
+}): string;
+/**
+ * Whether a run's main output is the absence of one: nothing at all, or the runtime's absence
+ * document, matched by its whole shape (exactly its keys, each of the type the runtime writes) and
+ * never by its `absent` key alone, since a method's own output may carry such a field. The same
+ * rule `cli-python` applies.
+ */
+export declare function isAbsence(mainStuff: unknown): boolean;
+/**
+ * Print a finished run's main output on stdout, as the method produced it: indented JSON,
+ * unvalidated and unrepaired, a list included whichever shape it arrived in. An output the method
+ * left absent prints `null`, and a line on stderr says so.
+ */
+export declare function printResult(mainStuff: unknown, io: CommandIO): void;

package/dist/cli/present.js

@@ -0,0 +1,191 @@
+/**
+ * What the command prints: a finished run's result on stdout, and every failure on stderr.
+ *
+ * A failure is worded by the command from the error's typed fields, never from an SDK message
+ * whose wording is the SDK's own, wherever the fields carry what a person needs: the API's reason,
+ * the next step it advises and the request id support asks for. That keeps the two commands, this
+ * one and its Python twin, saying the same thing for the same answer, which is what the recorded
+ * case table holds them to.
+ */
+import { ApiResponseError, ApiUnreachableError, InputPreparationError, InvalidInputValueError, InvalidLocalSourceError, MethodLoadError, PipelineRequestError, RejectedAssetError, RunFailedError, UnsupportedUploadCapabilityError, UploadAuthenticationError, UploadTransportError, } from "../index.js";
+import { CommandError, EXIT_FAILED, EXIT_USAGE } from "./io.js";
+/** Word any failure for stderr and choose its exit code. */
+export function presentError(error) {
+    if (error instanceof CommandError) {
+        const first = error.bare ? error.message : `Error: ${error.message}`;
+        return { lines: [first, ...error.details], exitCode: error.exitCode };
+    }
+    if (error instanceof RunFailedError) {
+        const report = error.error;
+        const lines = [`Error: run ${error.runId} ended with status ${error.status}.`];
+        lines.push(`Reason: ${report?.message ?? error.message}`);
+        if (report?.user_action?.detail)
+            lines.push(`Next step: ${report.user_action.detail}`);
+        return { lines, exitCode: EXIT_FAILED };
+    }
+    if (error instanceof InvalidLocalSourceError) {
+        // A file the inputs name that cannot be read is the inputs' fault, as an unreadable inputs
+        // file is, so it is a usage error.
+        return {
+            lines: [
+                `Error: ${error.message}`,
+                "A relative path in the inputs resolves against the current directory.",
+            ],
+            exitCode: EXIT_USAGE,
+        };
+    }
+    if (error instanceof InvalidInputValueError) {
+        // A value at a file input that is no file, such as a data: URL that does not decode or a
+        // number, is the inputs' fault too.
+        return {
+            lines: [
+                "Error: the inputs hold a value at a file input that cannot be read as a file.",
+                `Reason: ${error.message}`,
+                FILE_INPUT_FORMS,
+            ],
+            exitCode: EXIT_USAGE,
+        };
+    }
+    if (error instanceof MethodLoadError) {
+        // The same lines whichever route said so: the input preparation here, the pipe I/O call of
+        // `--inputs-template` and `script` in `source.ts`.
+        return {
+            lines: [
+                METHOD_DOES_NOT_LOAD,
+                ...loadFailureLines(error.validationErrors, error.serverMessage),
+            ],
+            exitCode: EXIT_FAILED,
+        };
+    }
+    if (error instanceof RejectedAssetError ||
+        error instanceof UploadAuthenticationError ||
+        error instanceof UnsupportedUploadCapabilityError ||
+        error instanceof UploadTransportError) {
+        return presentUploadFailure(error);
+    }
+    if (error instanceof InputPreparationError && error.cause instanceof ApiResponseError) {
+        return presentRefusal(error.cause);
+    }
+    if (error instanceof ApiResponseError) {
+        return presentRefusal(error);
+    }
+    if (error instanceof ApiUnreachableError) {
+        return {
+            lines: [
+                `Error: could not reach the Pipelex API at ${error.apiUrl} (${error.code ?? "network error"}).`,
+            ],
+            exitCode: EXIT_FAILED,
+        };
+    }
+    if (error instanceof PipelineRequestError) {
+        return { lines: [`Error: ${error.message}`], exitCode: EXIT_FAILED };
+    }
+    const detail = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+    return { lines: [`Error: unexpected failure, ${detail}`], exitCode: EXIT_FAILED };
+}
+/**
+ * A file the inputs name that could not be uploaded: which file, the status the upload route
+ * answered when it answered, and the SDK's own sentence, which says what the status means for an
+ * upload (a file past the size limit, a deployment without upload), followed by the advice and the
+ * request id of the API's answer when it carries them.
+ */
+function presentUploadFailure(error) {
+    const cause = error.cause instanceof ApiResponseError ? error.cause : undefined;
+    const status = "status" in error && typeof error.status === "number" ? error.status : cause?.status;
+    const what = error.filename === undefined ? "an upload failed" : `the upload of "${error.filename}" failed`;
+    const lines = [`Error: ${what}${status === undefined ? "" : ` (status ${status})`}.`];
+    lines.push(`Reason: ${error.message}`);
+    if (cause?.userAction?.detail)
+        lines.push(`Next step: ${cause.userAction.detail}`);
+    if (cause?.requestId)
+        lines.push(`Request id: ${cause.requestId}`);
+    return { lines, exitCode: EXIT_FAILED };
+}
+/** An answer the API gave instead of a result: its status, its reason and its advice. */
+function presentRefusal(error) {
+    const lines = error.status >= 200 && error.status < 300
+        ? [`Error: the API's answer could not be read (status ${error.status}).`]
+        : [`Error: the API refused the request (status ${error.status}).`];
+    lines.push(`Reason: ${error.serverMessage ?? error.title ?? "the answer gives no reason"}`);
+    for (const item of error.validationErrors ?? [])
+        lines.push(validationLine(item));
+    if (error.userAction?.detail)
+        lines.push(`Next step: ${error.userAction.detail}`);
+    if (error.requestId)
+        lines.push(`Request id: ${error.requestId}`);
+    return { lines, exitCode: EXIT_FAILED };
+}
+/** What a file input takes, the hint under a value it cannot take. */
+const FILE_INPUT_FORMS = 'A file input takes a local path, an http(s) or pipelex-storage:// URL, a data: URL, or an object whose "url" is one of these.';
+/** The first line of a method that does not load, after `Error: `. */
+export const METHOD_DOES_NOT_LOAD_SENTENCE = "the method does not load.";
+const METHOD_DOES_NOT_LOAD = `Error: ${METHOD_DOES_NOT_LOAD_SENTENCE}`;
+/**
+ * The lines under "the method does not load": one per validation item that carries a string
+ * `category` and `message`, the rule the SDK reads a failed load's items by, and when there is
+ * none, the answer's own message.
+ */
+export function loadFailureLines(items, message) {
+    const lines = (Array.isArray(items) ? items : []).filter(isLoadItem).map(validationLine);
+    if (lines.length === 0) {
+        lines.push(`  - ${typeof message === "string" ? message : "the answer gives no reason"}`);
+    }
+    return lines;
+}
+function isLoadItem(value) {
+    return (isPlainObject(value) && typeof value.category === "string" && typeof value.message === "string");
+}
+/** One validation error, as an indented line naming its file when it has one. */
+export function validationLine(item) {
+    const source = typeof item.source === "string" && item.source !== "" ? `${item.source}: ` : "";
+    return `  - ${source}${item.message}`;
+}
+/** The keys of the runtime's absence document, and no other. */
+const ABSENCE_KEYS = ["absent", "variable_name", "kind", "reason", "producing_pipe", "upstream"];
+const ABSENCE_KINDS = ["declared_absent", "skipped", "not_provided"];
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Whether a run's main output is the absence of one: nothing at all, or the runtime's absence
+ * document, matched by its whole shape (exactly its keys, each of the type the runtime writes) and
+ * never by its `absent` key alone, since a method's own output may carry such a field. The same
+ * rule `cli-python` applies.
+ */
+export function isAbsence(mainStuff) {
+    if (mainStuff === null || mainStuff === undefined)
+        return true;
+    if (!isPlainObject(mainStuff))
+        return false;
+    const keys = Object.keys(mainStuff);
+    if (keys.length !== ABSENCE_KEYS.length || !ABSENCE_KEYS.every((key) => keys.includes(key))) {
+        return false;
+    }
+    const { absent, variable_name, kind, reason, producing_pipe, upstream } = mainStuff;
+    return (absent === true &&
+        typeof variable_name === "string" &&
+        typeof kind === "string" &&
+        ABSENCE_KINDS.includes(kind) &&
+        typeof reason === "string" &&
+        (producing_pipe === null || typeof producing_pipe === "string") &&
+        (upstream === null || isPlainObject(upstream)));
+}
+/**
+ * Print a finished run's main output on stdout, as the method produced it: indented JSON,
+ * unvalidated and unrepaired, a list included whichever shape it arrived in. An output the method
+ * left absent prints `null`, and a line on stderr says so.
+ */
+export function printResult(mainStuff, io) {
+    if (isAbsence(mainStuff)) {
+        io.writeStdout("null\n");
+        if (isPlainObject(mainStuff)) {
+            io.writeStderr(`The method left its output "${String(mainStuff.variable_name)}" absent (${String(mainStuff.reason)}), so the result is null.\n`);
+        }
+        else {
+            io.writeStderr("The method produced no output, so the result is null.\n");
+        }
+        return;
+    }
+    io.writeStdout(`${JSON.stringify(mainStuff, null, 2)}\n`);
+}
+//# sourceMappingURL=present.js.map

package/dist/cli/present.js.map

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

package/dist/cli/run.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `pipelex-sdk run`: run one method and print its main output.
+ *
+ * Every check that needs no request comes first, in this order, so that a mistake costs nothing:
+ * the flags, `--pipe`'s form, the method (a path is read from disk), the inputs, the poll interval
+ * and the key. Then the inputs are prepared, which uploads each local file at a file input; the
+ * run is started through the SDK's start-and-wait, whose `onStarted` gives the run id to stderr
+ * as soon as the run exists; and the main output reaches stdout once the run completes, however
+ * long that takes.
+ */
+import type { CommandIO } from "./io.js";
+/** Run `pipelex-sdk run` and return its exit code. */
+export declare function runCommandRun(args: readonly string[], io: CommandIO): Promise<number>;
+/** The line under a failure that leaves it unknown whether a run was created. */
+export declare const RUN_MAY_HAVE_STARTED_LINE = "A run may have started on the server without the command learning of it, so check before starting it again.";
+/** The line under a failure met while waiting on a run that exists. */
+export declare function runStillGoingLine(runId: string): string;