@pipelex/sdk 0.33.0 → 0.34.1

package/dist/cli/script.js

@@ -0,0 +1,212 @@
+/**
+ * `pipelex-sdk script`: write the per-method command, a short shell script that runs one method
+ * through this SDK's `run`, its version pinned.
+ *
+ * The checks that need no request come first, in this order: the flags, `--pipe`'s form, a
+ * control character in any value the script would carry, the method's form (a local bundle is
+ * refused), `--name`, `--dir`, the target file when its name is already known, and the key. Then
+ * one pipe I/O call checks the method and the pipe, which spends no inference; a catalog id with
+ * no `--name` is named from its catalog entry; and the file is written, never over an existing
+ * one, with the permissions of an executable, an interrupt meanwhile waiting until it is whole.
+ */
+import { lstat, open, stat, unlink } from "node:fs/promises";
+import { resolve } from "node:path";
+import { SDK_VERSION } from "../index.js";
+import { parseFlags } from "./args.js";
+import { systemReason } from "./bundle.js";
+import { makeClient } from "./environment.js";
+import { SCRIPT_HELP } from "./help.js";
+import { CommandError, EXIT_INTERRUPTED, EXIT_OK, Interrupted, untilInterrupted, usageError, } from "./io.js";
+import { addressName, addressTag, checkPipeRef, classifyMethod, hasControlCharacter, kebabCase, scriptNameProblem, shellQuote, } from "./method.js";
+import { describePipe } from "./source.js";
+const SCRIPT_FLAGS = {
+    method: { type: "string" },
+    pipe: { type: "string" },
+    name: { type: "string" },
+    dir: { type: "string" },
+};
+/** The package a written script runs, and what its runner needs. */
+export const SCRIPT_RUNNER = `npx --yes @pipelex/sdk@${SDK_VERSION}`;
+export const SCRIPT_WRITER = "@pipelex/sdk";
+export const SCRIPT_NEEDS = "Node 22.12 or later";
+/** Run `pipelex-sdk script` and return its exit code. */
+export async function runCommandScript(args, io) {
+    const flags = parseFlags("script", args, SCRIPT_FLAGS);
+    if (flags.help) {
+        io.writeStdout(SCRIPT_HELP);
+        return EXIT_OK;
+    }
+    const method = flags.strings.get("method");
+    if (method === undefined) {
+        throw usageError("--method is required.", [
+            "Run 'pipelex-sdk script --help' to see its flags.",
+        ]);
+    }
+    const pipe = flags.strings.get("pipe");
+    if (pipe !== undefined)
+        checkPipeRef(pipe);
+    const givenName = flags.strings.get("name");
+    for (const [flag, value] of [
+        ["--method", method],
+        ["--pipe", pipe],
+        ["--name", givenName],
+    ]) {
+        if (value !== undefined && hasControlCharacter(value)) {
+            throw usageError(`${flag} holds a control character, which no line of a script may carry.`);
+        }
+    }
+    const selector = classifyMethod(method);
+    if (selector.kind === "path") {
+        throw usageError(`script takes a method address or a catalog id, and "${method}" is neither: a script naming a local bundle breaks as soon as the script or the bundle moves.`, [
+            "Publish the method in a git repository and pass its address: github.com/<owner>/<repo>[/<package>]@<tag>",
+            "Or save it to your organization's catalog and pass its id: mt_...",
+            "To run a local bundle, use: pipelex-sdk run --method <path>",
+        ]);
+    }
+    const source = selector.kind === "address"
+        ? { kind: "address", methodRef: selector.methodRef }
+        : { kind: "catalog", methodId: selector.methodId };
+    if (givenName !== undefined) {
+        const problem = scriptNameProblem(givenName);
+        if (problem !== undefined)
+            throw usageError(`--name ${problem}.`);
+    }
+    const dir = flags.strings.get("dir");
+    const shownDir = dir === undefined ? "." : dir.replace(/\/+$/, "");
+    await checkDirectory(dir ?? ".");
+    let name = givenName;
+    if (name === undefined && source.kind === "address") {
+        name = defaultName(addressName(source.methodRef), method);
+    }
+    if (name !== undefined)
+        await checkFree(shownDir, name);
+    const client = makeClient(io);
+    try {
+        await describePipe(client, source, pipe, io.interrupt);
+        if (name === undefined && source.kind === "catalog") {
+            name = defaultName(await catalogName(client, source.methodId, io), method);
+            await checkFree(shownDir, name);
+        }
+    }
+    catch (error) {
+        if (!(error instanceof Interrupted))
+            throw error;
+        throw new CommandError("Interrupted. Nothing was written.", {
+            exitCode: EXIT_INTERRUPTED,
+            bare: true,
+        });
+    }
+    if (name === undefined)
+        throw new Error("a script's name is known once the method is checked");
+    if (source.kind === "address" && addressTag(source.methodRef) === undefined) {
+        io.writeStderr(`Warning: ${source.methodRef} has no tag, so the script runs whatever its repository's default branch holds each time it runs. Add @<tag> to pin a release.\n`);
+    }
+    const target = `${shownDir}/${name}`;
+    // The last check before the file exists: an interrupt that landed during the checks above
+    // writes nothing.
+    if (io.interrupt.aborted) {
+        throw new CommandError("Interrupted. Nothing was written.", {
+            exitCode: EXIT_INTERRUPTED,
+            bare: true,
+        });
+    }
+    // The write is not raced with the interrupt: one that lands meanwhile waits for the file to be
+    // whole, then says it was written, so that the message is true wherever it lands.
+    await writeScript(target, scriptBody(name, method, pipe));
+    if (io.interrupt.aborted) {
+        throw new CommandError(`Interrupted. ${target} was written.`, {
+            exitCode: EXIT_INTERRUPTED,
+            bare: true,
+        });
+    }
+    io.writeStdout(`${target}\n`);
+    io.writeStderr(`Wrote ${target}. Run it with: ${target} --inputs inputs.json\n`);
+    return EXIT_OK;
+}
+/**
+ * Create the file, executable, refusing one that exists, a dangling link included (`wx`). A write
+ * that fails once the file exists removes it, so that a script is either whole or absent: a
+ * truncated one would run half a command, and would make the next attempt say it already exists.
+ * The one exception is a second Ctrl-C, which ends the process at once (`cli.ts`): landing between
+ * the file's creation and the end of its write, it leaves that file behind, empty or partial, as
+ * `docs/cli.md` says. On a local disk that takes no time, but a write can block on a stalled mount.
+ */
+async function writeScript(target, body) {
+    const path = resolve(target);
+    let handle;
+    try {
+        handle = await open(path, "wx", 0o755);
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            throw alreadyThere(target);
+        throw usageError(`cannot write "${target}".`, [`Reason: ${systemReason(error)}`]);
+    }
+    // The write's own failure is the one reported, a failed close the next.
+    const failures = [];
+    await handle.writeFile(body).catch((error) => failures.push(error));
+    await handle.close().catch((error) => failures.push(error));
+    if (failures.length > 0) {
+        await unlink(path).catch(() => undefined);
+        throw usageError(`cannot write "${target}".`, [`Reason: ${systemReason(failures[0])}`]);
+    }
+}
+/**
+ * The script's text: the shebang, a header saying what it runs, which SDK wrote it, what it needs
+ * and how to use it, and the one line that runs it, every value single-quoted.
+ */
+export function scriptBody(name, method, pipe) {
+    const pipeArgument = pipe === undefined ? "" : ` --pipe ${shellQuote(pipe)}`;
+    return [
+        "#!/bin/sh",
+        `# ${name}: runs ${method} on the Pipelex API.`,
+        `# Written by ${SCRIPT_WRITER} ${SDK_VERSION}. Needs ${SCRIPT_NEEDS}, and PIPELEX_API_KEY in the environment.`,
+        `# Usage: ./${name} --inputs inputs.json, or ./${name} --inputs-template to see what to fill in.`,
+        `exec ${SCRIPT_RUNNER} run --method ${shellQuote(method)}${pipeArgument} "$@"`,
+        "",
+    ].join("\n");
+}
+/** A default name, held to the rules of a file name, or the usage error asking for `--name`. */
+function defaultName(candidate, method) {
+    if (scriptNameProblem(candidate) !== undefined) {
+        throw usageError(`no script name can be made from "${method}"; give one with --name.`);
+    }
+    return candidate;
+}
+/**
+ * A catalog method's name, kebab-cased, read from its catalog entry. An entry whose name is
+ * missing or not a string gives an empty one, which asks for `--name` as an unusable name does.
+ */
+async function catalogName(client, methodId, io) {
+    const entry = await untilInterrupted(() => client.getMethod(methodId), io.interrupt);
+    const name = entry.name;
+    return typeof name === "string" ? kebabCase(name) : "";
+}
+async function checkDirectory(dir) {
+    let found;
+    try {
+        found = await stat(resolve(dir));
+    }
+    catch (error) {
+        throw usageError(`--dir "${dir}" does not exist.`, [`Reason: ${systemReason(error)}`]);
+    }
+    if (!found.isDirectory())
+        throw usageError(`--dir "${dir}" is not a directory.`);
+}
+/** Refuse a target that exists, whatever it is, a link that leads nowhere included. */
+async function checkFree(shownDir, name) {
+    const target = `${shownDir}/${name}`;
+    try {
+        await lstat(resolve(target));
+    }
+    catch {
+        return;
+    }
+    throw alreadyThere(target);
+}
+function alreadyThere(target) {
+    return usageError(`"${target}" already exists, and script never overwrites a file.`, [
+        "Remove it, or choose another name with --name or another directory with --dir.",
+    ]);
+}
+//# sourceMappingURL=script.js.map

package/dist/cli/script.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"script.js","sourceRoot":"","sources":["../../src/cli/script.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE7D,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,OAAO,EACP,WAAW,EACX,gBAAgB,EAChB,UAAU,GACX,MAAM,SAAS,CAAC;AAEjB,OAAO,EACL,WAAW,EACX,UAAU,EACV,YAAY,EACZ,cAAc,EACd,mBAAmB,EACnB,SAAS,EACT,iBAAiB,EACjB,UAAU,GACX,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C,MAAM,YAAY,GAAG;IACnB,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;IAC1B,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;IACxB,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;IACxB,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;CACf,CAAC;AAEX,oEAAoE;AACpE,MAAM,CAAC,MAAM,aAAa,GAAG,0BAA0B,WAAW,EAAE,CAAC;AACrE,MAAM,CAAC,MAAM,aAAa,GAAG,cAAc,CAAC;AAC5C,MAAM,CAAC,MAAM,YAAY,GAAG,qBAAqB,CAAC;AAElD,yDAAyD;AACzD,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAAuB,EAAE,EAAa;IAC3E,MAAM,KAAK,GAAG,UAAU,CAAC,QAAQ,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC;IACvD,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;QACf,EAAE,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;QAC5B,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC3C,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,UAAU,CAAC,uBAAuB,EAAE;YACxC,mDAAmD;SACpD,CAAC,CAAC;IACL,CAAC;IACD,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACvC,IAAI,IAAI,KAAK,SAAS;QAAE,YAAY,CAAC,IAAI,CAAC,CAAC;IAC3C,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC5C,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI;QAC1B,CAAC,UAAU,EAAE,MAAM,CAAC;QACpB,CAAC,QAAQ,EAAE,IAAI,CAAC;QAChB,CAAC,QAAQ,EAAE,SAAS,CAAC;KACb,EAAE,CAAC;QACX,IAAI,KAAK,KAAK,SAAS,IAAI,mBAAmB,CAAC,KAAK,CAAC,EAAE,CAAC;YACtD,MAAM,UAAU,CAAC,GAAG,IAAI,kEAAkE,CAAC,CAAC;QAC9F,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC,IAAI,QAAQ,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QAC7B,MAAM,UAAU,CACd,uDAAuD,MAAM,gGAAgG,EAC7J;YACE,0GAA0G;YAC1G,mEAAmE;YACnE,6DAA6D;SAC9D,CACF,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GACV,QAAQ,CAAC,IAAI,KAAK,SAAS;QACzB,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,CAAC,SAAS,EAAE;QACpD,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE,CAAC;IAEvD,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,MAAM,OAAO,GAAG,iBAAiB,CAAC,SAAS,CAAC,CAAC;QAC7C,IAAI,OAAO,KAAK,SAAS;YAAE,MAAM,UAAU,CAAC,UAAU,OAAO,GAAG,CAAC,CAAC;IACpE,CAAC;IACD,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACrC,MAAM,QAAQ,GAAG,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACnE,MAAM,cAAc,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC;IAEjC,IAAI,IAAI,GAAuB,SAAS,CAAC;IACzC,IAAI,IAAI,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QACpD,IAAI,GAAG,WAAW,CAAC,WAAW,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,CAAC;IAC5D,CAAC;IACD,IAAI,IAAI,KAAK,SAAS;QAAE,MAAM,SAAS,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IAExD,MAAM,MAAM,GAAG,UAAU,CAAC,EAAE,CAAC,CAAC;IAC9B,IAAI,CAAC;QACH,MAAM,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC;QACvD,IAAI,IAAI,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YACpD,IAAI,GAAG,WAAW,CAAC,MAAM,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;YAC3E,MAAM,SAAS,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,CAAC,KAAK,YAAY,WAAW,CAAC;YAAE,MAAM,KAAK,CAAC;QACjD,MAAM,IAAI,YAAY,CAAC,mCAAmC,EAAE;YAC1D,QAAQ,EAAE,gBAAgB;YAC1B,IAAI,EAAE,IAAI;SACX,CAAC,CAAC;IACL,CAAC;IACD,IAAI,IAAI,KAAK,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IAE/F,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,IAAI,UAAU,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,SAAS,EAAE,CAAC;QAC5E,EAAE,CAAC,WAAW,CACZ,YAAY,MAAM,CAAC,SAAS,kIAAkI,CAC/J,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAG,GAAG,QAAQ,IAAI,IAAI,EAAE,CAAC;IACrC,0FAA0F;IAC1F,kBAAkB;IAClB,IAAI,EAAE,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC;QACzB,MAAM,IAAI,YAAY,CAAC,mCAAmC,EAAE;YAC1D,QAAQ,EAAE,gBAAgB;YAC1B,IAAI,EAAE,IAAI;SACX,CAAC,CAAC;IACL,CAAC;IACD,+FAA+F;IAC/F,kFAAkF;IAClF,MAAM,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;IAC1D,IAAI,EAAE,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC;QACzB,MAAM,IAAI,YAAY,CAAC,gBAAgB,MAAM,eAAe,EAAE;YAC5D,QAAQ,EAAE,gBAAgB;YAC1B,IAAI,EAAE,IAAI;SACX,CAAC,CAAC;IACL,CAAC;IACD,EAAE,CAAC,WAAW,CAAC,GAAG,MAAM,IAAI,CAAC,CAAC;IAC9B,EAAE,CAAC,WAAW,CAAC,SAAS,MAAM,kBAAkB,MAAM,yBAAyB,CAAC,CAAC;IACjF,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;GAOG;AACH,KAAK,UAAU,WAAW,CAAC,MAAc,EAAE,IAAY;IACrD,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7B,IAAI,MAAkB,CAAC;IACvB,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;IACzC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;YAAE,MAAM,YAAY,CAAC,MAAM,CAAC,CAAC;QACnF,MAAM,UAAU,CAAC,iBAAiB,MAAM,IAAI,EAAE,CAAC,WAAW,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;IACpF,CAAC;IACD,wEAAwE;IACxE,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,MAAM,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IAC7E,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACrE,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC1C,MAAM,UAAU,CAAC,iBAAiB,MAAM,IAAI,EAAE,CAAC,WAAW,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC1F,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,MAAc,EAAE,IAAwB;IAC/E,MAAM,YAAY,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;IAC7E,OAAO;QACL,WAAW;QACX,KAAK,IAAI,UAAU,MAAM,sBAAsB;QAC/C,gBAAgB,aAAa,IAAI,WAAW,WAAW,YAAY,2CAA2C;QAC9G,cAAc,IAAI,+BAA+B,IAAI,4CAA4C;QACjG,QAAQ,aAAa,iBAAiB,UAAU,CAAC,MAAM,CAAC,GAAG,YAAY,OAAO;QAC9E,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,gGAAgG;AAChG,SAAS,WAAW,CAAC,SAAiB,EAAE,MAAc;IACpD,IAAI,iBAAiB,CAAC,SAAS,CAAC,KAAK,SAAS,EAAE,CAAC;QAC/C,MAAM,UAAU,CAAC,oCAAoC,MAAM,0BAA0B,CAAC,CAAC;IACzF,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,KAAK,UAAU,WAAW,CACxB,MAAwB,EACxB,QAAgB,EAChB,EAAa;IAEb,MAAM,KAAK,GAAG,MAAM,gBAAgB,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC;IACrF,MAAM,IAAI,GAAY,KAAK,CAAC,IAAI,CAAC;IACjC,OAAO,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACzD,CAAC;AAED,KAAK,UAAU,cAAc,CAAC,GAAW;IACvC,IAAI,KAAuC,CAAC;IAC5C,IAAI,CAAC;QACH,KAAK,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;IACnC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,UAAU,CAAC,UAAU,GAAG,mBAAmB,EAAE,CAAC,WAAW,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;IACzF,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE;QAAE,MAAM,UAAU,CAAC,UAAU,GAAG,uBAAuB,CAAC,CAAC;AACnF,CAAC;AAED,uFAAuF;AACvF,KAAK,UAAU,SAAS,CAAC,QAAgB,EAAE,IAAY;IACrD,MAAM,MAAM,GAAG,GAAG,QAAQ,IAAI,IAAI,EAAE,CAAC;IACrC,IAAI,CAAC;QACH,MAAM,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;IACT,CAAC;IACD,MAAM,YAAY,CAAC,MAAM,CAAC,CAAC;AAC7B,CAAC;AAED,SAAS,YAAY,CAAC,MAAc;IAClC,OAAO,UAAU,CAAC,IAAI,MAAM,uDAAuD,EAAE;QACnF,gFAAgF;KACjF,CAAC,CAAC;AACL,CAAC"}

package/dist/cli/source.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The method as each route names it, and the one pipe I/O call that checks it.
+ *
+ * A bundle read from disk travels to the pipe I/O route as `files`, each file under its name in the
+ * bundle, and to the run as `mthds_contents`, in the same order. An address travels as
+ * `method_ref` and a catalog id as `method_id`, both resolved by the server.
+ */
+import type { PipeInputFormDescriptor, PipelexApiClient, PipeIOValidReport, PipelexStartOptions } from "../index.js";
+import type { BundleFile } from "./bundle.js";
+/** A method the command can send: a bundle read from disk, an address or a catalog id. */
+export type MethodSource = {
+    readonly kind: "bundle";
+    readonly files: readonly BundleFile[];
+} | {
+    readonly kind: "address";
+    readonly methodRef: string;
+} | {
+    readonly kind: "catalog";
+    readonly methodId: string;
+};
+/** The method as the crate routes and the input preparation name it. */
+export type CrateSelector = {
+    files: Array<{
+        content: string;
+        source: string;
+    }>;
+} | {
+    method_ref: string;
+} | {
+    method_id: string;
+};
+export declare function crateSelector(source: MethodSource): CrateSelector;
+/** The method as the run routes name it. */
+export declare function runSelector(source: MethodSource): PipelexStartOptions;
+/** A pipe I/O answer's valid arm, and the input form of the pipe it selected. */
+export interface DescribedPipe {
+    readonly report: PipeIOValidReport;
+    readonly pipeRef: string;
+    readonly descriptor: PipeInputFormDescriptor;
+}
+/**
+ * Ask `POST /v1/pipe-io` for the pipe the method and `--pipe` select, which spends no inference:
+ * the same selection the run's input preparation makes.
+ *
+ * @throws {CommandError} When the method does not load, or the answer does not describe the pipe
+ *   it selected. A refusal of the request itself propagates as the SDK's `ApiResponseError`.
+ * @throws {Interrupted} When the person interrupts the wait.
+ */
+export declare function describePipe(client: PipelexApiClient, source: MethodSource, pipe: string | undefined, interrupt: AbortSignal): Promise<DescribedPipe>;

package/dist/cli/source.js

@@ -0,0 +1,71 @@
+/**
+ * The method as each route names it, and the one pipe I/O call that checks it.
+ *
+ * A bundle read from disk travels to the pipe I/O route as `files`, each file under its name in the
+ * bundle, and to the run as `mthds_contents`, in the same order. An address travels as
+ * `method_ref` and a catalog id as `method_id`, both resolved by the server.
+ */
+import { CommandError, EXIT_FAILED, untilInterrupted } from "./io.js";
+import { loadFailureLines, METHOD_DOES_NOT_LOAD_SENTENCE } from "./present.js";
+export function crateSelector(source) {
+    switch (source.kind) {
+        case "bundle":
+            return { files: source.files.map((file) => ({ content: file.content, source: file.name })) };
+        case "address":
+            return { method_ref: source.methodRef };
+        case "catalog":
+            return { method_id: source.methodId };
+    }
+}
+/** The method as the run routes name it. */
+export function runSelector(source) {
+    switch (source.kind) {
+        case "bundle":
+            return { mthds_contents: source.files.map((file) => file.content) };
+        case "address":
+            return { method_ref: source.methodRef };
+        case "catalog":
+            return { method_id: source.methodId };
+    }
+}
+/**
+ * Ask `POST /v1/pipe-io` for the pipe the method and `--pipe` select, which spends no inference:
+ * the same selection the run's input preparation makes.
+ *
+ * @throws {CommandError} When the method does not load, or the answer does not describe the pipe
+ *   it selected. A refusal of the request itself propagates as the SDK's `ApiResponseError`.
+ * @throws {Interrupted} When the person interrupts the wait.
+ */
+export async function describePipe(client, source, pipe, interrupt) {
+    const request = {
+        ...crateSelector(source),
+        ...(pipe === undefined ? {} : { pipe_ref: pipe }),
+    };
+    const answer = await untilInterrupted(() => client.pipeIo(request), interrupt);
+    if (!isPlainObject(answer) || typeof answer.is_valid !== "boolean") {
+        throw new CommandError("the API's pipe I/O answer says neither that the method loads nor why it does not.", {
+            exitCode: EXIT_FAILED,
+        });
+    }
+    if (!answer.is_valid) {
+        throw new CommandError(METHOD_DOES_NOT_LOAD_SENTENCE, {
+            exitCode: EXIT_FAILED,
+            details: loadFailureLines(answer.validation_errors, answer.message),
+        });
+    }
+    const report = answer;
+    const pipeRef = report.pipe_ref;
+    const inputForm = report.input_form;
+    if (typeof pipeRef !== "string" ||
+        !isPlainObject(inputForm) ||
+        !isPlainObject(inputForm[pipeRef])) {
+        throw new CommandError("the API's pipe I/O answer does not describe the pipe it selected.", {
+            exitCode: EXIT_FAILED,
+        });
+    }
+    return { report, pipeRef, descriptor: inputForm[pipeRef] };
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=source.js.map

package/dist/cli/source.js.map

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

package/dist/cli.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * The `pipelex-sdk` executable, which `package.json` declares as the package's one `bin`, so that
+ * `npx @pipelex/sdk run …` runs it. It hands the command the real process — its arguments, its
+ * environment, its streams and Ctrl-C — and exits with the command's code (`docs/cli.md`).
+ *
+ * It uses no top-level `await`, as no module of `dist/` does, so that the package stays loadable
+ * through `require(ESM)` (`docs/architecture.md`, "Module format & packaging").
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+/**
+ * The `pipelex-sdk` executable, which `package.json` declares as the package's one `bin`, so that
+ * `npx @pipelex/sdk run …` runs it. It hands the command the real process — its arguments, its
+ * environment, its streams and Ctrl-C — and exits with the command's code (`docs/cli.md`).
+ *
+ * It uses no top-level `await`, as no module of `dist/` does, so that the package stays loadable
+ * through `require(ESM)` (`docs/architecture.md`, "Module format & packaging").
+ */
+import process from "node:process";
+import { EXIT_INTERRUPTED, ignoreClosedPipe } from "./cli/io.js";
+import { runCommand } from "./cli/main.js";
+const interrupt = new AbortController();
+// Once: a second Ctrl-C finds no handler and ends the process the default way.
+process.once("SIGINT", () => interrupt.abort());
+// A reader that stops early (`| head`, `2>&1 | head -1`) closes the pipe on either stream.
+ignoreClosedPipe(process.stdout);
+ignoreClosedPipe(process.stderr);
+void runCommand(process.argv.slice(2), {
+    env: process.env,
+    readStdin: async () => {
+        const chunks = [];
+        for await (const chunk of process.stdin)
+            chunks.push(chunk);
+        return Buffer.concat(chunks);
+    },
+    writeStdout: (text) => {
+        process.stdout.write(text);
+    },
+    writeStderr: (text) => {
+        process.stderr.write(text);
+    },
+    interrupt: interrupt.signal,
+}).then(exitWhenFlushed);
+/**
+ * Exit once both streams have flushed, rather than when the event loop empties: a request the
+ * command stopped waiting for on Ctrl-C, such as the start of a run, would otherwise hold the
+ * process open until the API answers it.
+ *
+ * After Ctrl-C, the process ends by the signal itself rather than by `process.exit(130)`, which a
+ * POSIX shell reports as the same status, 130: Node's exit waits for its worker threads, and one
+ * can be blocked for good in a read the command stopped waiting for, such as `--inputs` naming a
+ * named pipe no one writes to, or `/dev/stdin` on a terminal. Ending by the signal also tells a
+ * calling shell loop that the person interrupted. Windows has no such signal to end by, and exits
+ * with 130.
+ */
+async function exitWhenFlushed(code) {
+    await flush(process.stdout);
+    await flush(process.stderr);
+    if (code === EXIT_INTERRUPTED && interrupt.signal.aborted && process.platform !== "win32") {
+        // The once-only handler is gone, so SIGINT has its default action again: ending the process.
+        process.kill(process.pid, "SIGINT");
+    }
+    process.exit(code);
+}
+function flush(stream) {
+    return new Promise((resolve) => {
+        if (stream.destroyed || !stream.writable) {
+            resolve();
+            return;
+        }
+        stream.write("", () => resolve());
+    });
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;GAOG;AAEH,OAAO,OAAO,MAAM,cAAc,CAAC;AAGnC,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C,MAAM,SAAS,GAAG,IAAI,eAAe,EAAE,CAAC;AACxC,+EAA+E;AAC/E,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC,CAAC;AAEhD,2FAA2F;AAC3F,gBAAgB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;AACjC,gBAAgB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;AAEjC,KAAK,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;IACrC,GAAG,EAAE,OAAO,CAAC,GAAG;IAChB,SAAS,EAAE,KAAK,IAAI,EAAE;QACpB,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,OAAO,CAAC,KAAK;YAAE,MAAM,CAAC,IAAI,CAAC,KAAe,CAAC,CAAC;QACtE,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC/B,CAAC;IACD,WAAW,EAAE,CAAC,IAAI,EAAE,EAAE;QACpB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IACD,WAAW,EAAE,CAAC,IAAI,EAAE,EAAE;QACpB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IACD,SAAS,EAAE,SAAS,CAAC,MAAM;CAC5B,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;AAEzB;;;;;;;;;;;GAWG;AACH,KAAK,UAAU,eAAe,CAAC,IAAY;IACzC,MAAM,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5B,MAAM,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5B,IAAI,IAAI,KAAK,gBAAgB,IAAI,SAAS,CAAC,MAAM,CAAC,OAAO,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QAC1F,6FAA6F;QAC7F,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IACtC,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACrB,CAAC;AAED,SAAS,KAAK,CAAC,MAAgB;IAC7B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,IAAI,MAAM,CAAC,SAAS,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;YACzC,OAAO,EAAE,CAAC;YACV,OAAO;QACT,CAAC;QACD,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/client.d.ts

@@ -1,6 +1,6 @@
 import type { MTHDSProtocol, ModelCategory, ModelDeck, RunOptions, StartOptions, VersionInfo } from "mthds/protocol";
-import type { CodegenRequest, CodegenResponse, DictPipeOutput, FormatResponse, LintResponse, MthdsFileItem, PipeIORequest, PipeIOResponse, PipelexRunResultStart, PipelexValidationResult, ResolveRequest, ResolveResponse, ValidateMethodSelector } from "./models.js";
-import { type GetRunResultOptions, type RunRead, type RunResults, type RunResultState, type WaitForResultOptions } from "./runs.js";
+import type { CodegenRequest, CodegenResponse, DictPipeOutput, FormatResponse, LintResponse, ModelCheckCategory, ModelReferenceVerdict, MthdsFileItem, PipeIORequest, PipeIOResponse, PipelexRunResultStart, PipelexValidationResult, ResolveRequest, ResolveResponse, ValidateMethodSelector } from "./models.js";
+import { type GetRunResultOptions, type RunRead, type RunResults, type RunResultState, type StartAndWaitForResultOptions, type WaitForResultOptions } from "./runs.js";
 import type { BillingPortalResponse, ChangePlanResponse, CheckoutResponse, InvoiceView, Membership, MembershipsResponse, ListMethodsQuery, MethodData, MethodDeletionAccepted, MethodPage, MethodSummary, MethodWriteInput, OnboardingSubmission, PipelexApiKeyCreated, PipelexApiKeyList, ListRunsQuery, RunHistoryItem, RunDetail, RunPage, PlanView, ResolvedStorageUrl, SubscriptionResponse, UpdateRunInput, UploadGrant, UploadGrantInput, UploadInput, UploadedFile, UserProfile } from "./product-models.js";
 import type { AppInfo } from "./user-agent.js";
 import type { UploadableAsset, UploadFileOptions, UploadRecord } from "./upload.js";
@@ -120,7 +120,8 @@ export interface PipelexApiClientOptions {
      * `{ name: "acme-invoicer", version: "1.4.0" }` →
      * `acme-invoicer/1.4.0 pipelex-sdk-js/<v> node/<v> (<os>; <arch>)`. Validated at
      * construction: a field that is not an RFC 9110 token throws a `TypeError`. See
-     * the workspace spec `docs/specs/client-identification.md`.
+     * the spec `conformance/specs/client-identification.md`, in the `conformance` repository
+     * beside the specs' tests.
      */
     appInfo?: AppInfo;
 }
@@ -199,8 +200,9 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
     private readObjectAnswer;
     /**
      * The JSON body of a 2xx answer, naming the route by its `path` from the origin as a refusal
-     * does. A body that is not JSON, an empty one included, is an answer the SDK cannot read, so it
-     * throws the `ApiResponseError` `unreadableAnswer` builds, with the parse failure as `cause`.
+     * does. A body that is not UTF-8, or not JSON, an empty one included, is an answer the SDK
+     * cannot read, so it throws the `ApiResponseError` `unreadableAnswer` builds, with the parse
+     * failure as `cause`.
      * The one place a success body is parsed.
      */
     private readAnswerAt;
@@ -419,6 +421,26 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
     private requestExtension;
     /** The model deck the runner can route to — `GET /v1/models[?type=]`. */
     models(category?: ModelCategory): Promise<ModelDeck>;
+    /**
+     * Check one model reference — `GET /v1/models/check?reference=<ref>[&type=<category>]`, a
+     * Pipelex API extension served by any `pipelex-api` runner from pipelex 0.78.0 and on the
+     * hosted API.
+     *
+     * Answers whether `reference` resolves on the runner, as what kind and to which model, from
+     * the parser and the deck lookups a validation runs. `reference` is written as a method's
+     * `model` field writes it — `$preset`, `@alias`, `~waterfall`, a bare handle, or a
+     * spelled-out namespace (`handle:gpt-4o`) — and is sent percent-encoded. `category` checks
+     * in that category alone; without it, the check covers every one.
+     *
+     * Returns a **200 verdict** whatever the resolution: a reference that resolves nowhere is
+     * `resolution: "not_found"` with the names it may have meant, never a thrown error. Narrow
+     * on `kind` to read the shape of `matches`. A request that cannot produce a verdict throws
+     * the typed `ApiResponseError`, a `422` whose `errorType` says why: `InvalidModelReference`
+     * (a blank reference, a sigil or a namespace alone, or one past the runner's length limit),
+     * `InvalidModelCategory` (an unknown `type`) or `ValidationError`. None of that is checked
+     * here, so the runner's rule is the only one.
+     */
+    checkModelReference(reference: string, category?: ModelCheckCategory): Promise<ModelReferenceVerdict>;
     /**
      * Protocol + implementation versions — `GET /v1/version` (always public).
      * The handshake for feature detection (hosted extensions or not).
@@ -538,8 +560,18 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * Whether the configured server serves the durable run lifecycle, decided
      * via the `GET /v1/version` handshake and cached for the client's lifetime. A
      * bare `pipelex-api` runner has no run store; anything else is assumed hosted.
-     * When the handshake itself fails, assume hosted (the SDK default) and let the
-     * start call surface the real error.
+     *
+     * The rule, the one the Python SDK follows: an answer that is not a usable
+     * version means assume hosted (the SDK default), and let the start surface the
+     * real error; no answer at all propagates, uncached. An answer is anything the
+     * server sent back: a non-2xx status, a body that is not JSON, not UTF-8 or no
+     * version, and a body that arrived but could not be decoded, such as a broken
+     * gzip stream, which `requestRaw` reports as an `ApiUnreachableError` carrying
+     * the decompressor's code (see `isUndecodableBody`).
+     *
+     * @throws {ApiUnreachableError} The handshake got no answer. Nothing is cached,
+     *   so the next call asks again, and no start is sent to a host that did not
+     *   answer: sending it would wait a second time for the same silence.
      */
     private supportsRunLifecycle;
     /**
@@ -549,8 +581,19 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      *   path that survives the gateway's ~30s synchronous ceiling.
      * - **Bare runner** (no run store): the blocking `POST /v1/execute`, which
      *   has no gateway cap off-platform and returns the native `pipe_output`.
+     *
+     * `pollOptions` are the wait's options, plus `onStarted`, called once with the
+     * start acknowledgement as soon as the durable run exists, so the caller holds
+     * the run's id while it waits; never on the blocking path, which has none to
+     * give; and `onStarting`, called right before each request that may create a
+     * run, so the caller knows until then that none exists (see
+     * `StartAndWaitForResultOptions`).
+     *
+     * `pollOptions.signal` is also read before the run is created: a caller that aborts while the
+     * version handshake is in flight gets its abort, and neither the start nor the blocking execute
+     * is sent. Once one of them is sent, the abort stops only the wait.
      */
-    startAndWaitForResult(options: PipelexStartOptions, pollOptions?: WaitForResultOptions): Promise<RunResults>;
+    startAndWaitForResult(options: PipelexStartOptions, pollOptions?: StartAndWaitForResultOptions): Promise<RunResults>;
     /** The authenticated user's profile — `GET /v1/me`. */
     getMe(): Promise<UserProfile>;
     /**
@@ -855,3 +898,22 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      */
     private executeBlocking;
 }
+/**
+ * Whether a request that failed `elapsedMs` after it was sent was cut off by the hosted gateway's
+ * ~30-second limit on a request it waits on, rather than refused.
+ *
+ * It is when, after at least ~28 seconds, the failure is a `503` or `504` answer, or the client's
+ * own time limit (`ApiUnreachableError` with the code `ABORT_TIMEOUT`). A fast `503` is the API
+ * saying the request was not handled, and any other unreachable host is never the gateway's
+ * cut-off, however long it took. The fetch API cannot say whether `ABORT_TIMEOUT` ran out before
+ * the connection was made, so it is read as the gateway's; with Node's own dispatcher it never
+ * does past the threshold, since undici gives up a connection that does not come after ten
+ * seconds (`UND_ERR_CONNECT_TIMEOUT`), the TLS handshake included. The Python SDK's
+ * `is_gateway_cut_off` reads the same failures, its `ABORT_TIMEOUT` being httpx's read or write
+ * timeout.
+ *
+ * The blocking `execute` turns such a failure into a `PipelineExecuteTimeoutError`. A caller timing
+ * a request that may create a run, such as `start` from `startAndWaitForResult`'s `onStarting`,
+ * reads it to know the server may still be handling the request the gateway gave up on.
+ */
+export declare function isGatewayCutOff(error: unknown, elapsedMs: number): boolean;