@pipelex/sdk 0.32.0 → 0.34.0

package/dist/cli/run.js

@@ -0,0 +1,290 @@
+/**
+ * `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 { ApiResponseError, ApiUnreachableError, MissingMainStuffError, PipelineExecuteTimeoutError, RunFailedError, isGatewayCutOff, renderInputsTemplate, } from "../index.js";
+import { parseFlags } from "./args.js";
+import { readBundle } from "./bundle.js";
+import { makeClient, readPollInterval } from "./environment.js";
+import { RUN_HELP } from "./help.js";
+import { readInputs } from "./inputs.js";
+import { CommandError, EXIT_INTERRUPTED, EXIT_OK, Interrupted, untilInterrupted, usageError, writeLines, } from "./io.js";
+import { checkPipeRef, classifyMethod } from "./method.js";
+import { presentError, printResult } from "./present.js";
+import { crateSelector, describePipe, runSelector } from "./source.js";
+const RUN_FLAGS = {
+    method: { type: "string" },
+    pipe: { type: "string" },
+    inputs: { type: "string" },
+    "inputs-template": { type: "boolean" },
+};
+/** Run `pipelex-sdk run` and return its exit code. */
+export async function runCommandRun(args, io) {
+    const flags = parseFlags("run", args, RUN_FLAGS);
+    if (flags.help) {
+        io.writeStdout(RUN_HELP);
+        return EXIT_OK;
+    }
+    const method = flags.strings.get("method");
+    if (method === undefined) {
+        throw usageError("--method is required.", ["Run 'pipelex-sdk run --help' to see its flags."]);
+    }
+    const inputsSource = flags.strings.get("inputs");
+    const templateOnly = flags.booleans.has("inputs-template");
+    if (templateOnly && inputsSource !== undefined) {
+        throw usageError("--inputs-template prints the inputs a run takes, so it takes no --inputs.");
+    }
+    const pipe = flags.strings.get("pipe");
+    if (pipe !== undefined)
+        checkPipeRef(pipe);
+    let stage = { kind: "local" };
+    try {
+        // Raced like the inputs read: a bundle on a stalled mount must not hold the command.
+        const source = await untilInterrupted(() => methodSource(method), io.interrupt);
+        const inputs = inputsSource === undefined ? undefined : await readInputs(inputsSource, io);
+        const intervalMs = readPollInterval(io);
+        const client = makeClient(io);
+        if (templateOnly) {
+            const described = await describePipe(client, source, pipe, io.interrupt);
+            const template = renderInputsTemplate(described.descriptor, {
+                explicit: false,
+                format: "json",
+            });
+            io.writeStdout(`${template}\n`);
+            return EXIT_OK;
+        }
+        const prepared = await prepare(client, source, pipe, inputs, io);
+        const results = await untilInterrupted(() => {
+            return client.startAndWaitForResult({
+                ...runSelector(source),
+                ...(pipe === undefined ? {} : { pipe_code: pipe }),
+                ...(prepared === undefined ? {} : { inputs: prepared }),
+            }, {
+                // A run takes as long as it takes: the command waits for it until it ends or the
+                // person interrupts.
+                timeoutMs: Number.POSITIVE_INFINITY,
+                ...(intervalMs === undefined ? {} : { intervalMs }),
+                signal: io.interrupt,
+                artifacts: ["main_stuff"],
+                onStarting: () => {
+                    // Only once a request that may create a run is about to leave: an interrupt before
+                    // it, during the version handshake included, starts nothing, and the command says so.
+                    stage = { kind: "starting", since: performance.now() };
+                },
+                onStarted: (ack) => {
+                    if (io.interrupt.aborted)
+                        return;
+                    stage = { kind: "started", runId: ack.pipeline_run_id };
+                    io.writeStderr(`Run started: ${ack.pipeline_run_id}\n`);
+                },
+            });
+        }, io.interrupt);
+        printResult(results.main_stuff, io);
+        return EXIT_OK;
+    }
+    catch (error) {
+        if (!(error instanceof Interrupted)) {
+            const runId = waitedOnRun(stage, error);
+            const warning = runId !== undefined
+                ? runStillGoingLine(runId)
+                : mayHaveStarted(stage, error)
+                    ? RUN_MAY_HAVE_STARTED_LINE
+                    : undefined;
+            if (warning === undefined)
+                throw error;
+            // A failure that says nothing of a run that exists, or may: a wrapper must not read it as a
+            // failed run and pay for another.
+            const presented = presentError(error);
+            writeLines(io, [...presented.lines, warning]);
+            return presented.exitCode;
+        }
+        throw new CommandError(interruptMessage(stage, templateOnly), {
+            exitCode: EXIT_INTERRUPTED,
+            bare: true,
+        });
+    }
+}
+/**
+ * The run a failure leaves going on the server: the run that exists when the failure is not its
+ * own outcome, a failed run or a completed one without its output, but an unreachable API or a
+ * refused poll.
+ */
+function waitedOnRun(stage, error) {
+    if (stage.kind !== "started")
+        return undefined;
+    if (error instanceof RunFailedError || error instanceof MissingMainStuffError)
+        return undefined;
+    return stage.runId;
+}
+/**
+ * Whether a transport failure proves the request never left, so that no run was created by it: it
+ * names a step of the connection's set-up, which no request follows. That is the name lookup or
+ * the connection itself failing (the system calls `getaddrinfo` and `connect`: an unknown host, a
+ * refused connection, no route to the host or the network, the system's connect time limit),
+ * undici's own connect time limit, which covers the TLS handshake, and a server certificate the
+ * TLS handshake refused. Several addresses each failing so, which Node reports together as an
+ * `AggregateError`, prove it too. A host that drops packets is a connection that never comes:
+ * undici gives it up after ten seconds (`UND_ERR_CONNECT_TIMEOUT`), before the time limit of any
+ * request the command sends, as the Python command meets httpx's connect timeout first and reads
+ * it the same way.
+ *
+ * Anything else may have come once the request had left, the Python command reading the same
+ * failures the same way. A reset (`ECONNRESET`) comes from a `read` whether the connection dropped
+ * during the TLS handshake or after the request, and so does an `EHOSTUNREACH` met once connected,
+ * so neither proves anything; nor does another TLS failure, which may come after the handshake;
+ * nor does the SDK's own time limit (`ABORT_TIMEOUT`), which fetch cannot place before or after
+ * the connection was made. Every request the command sends has a limit longer than undici's
+ * connect limit, so with Node's own dispatcher it runs out only once the request has left.
+ */
+function provesNothingSent(error) {
+    // The SDK keeps fetch's own failure as `cause`, and undici gives the transport's under it.
+    const fetchFailure = error.cause;
+    return fetchFailure instanceof Error && isConnectionSetupFailure(fetchFailure.cause);
+}
+function isConnectionSetupFailure(failure) {
+    if (failure instanceof AggregateError) {
+        return failure.errors.length > 0 && failure.errors.every(isConnectionSetupFailure);
+    }
+    if (typeof failure !== "object" || failure === null)
+        return false;
+    const { code, syscall } = failure;
+    if (typeof code === "string" && CONNECTION_SETUP_CODES.has(code))
+        return true;
+    return typeof syscall === "string" && CONNECTION_SETUP_CALLS.has(syscall);
+}
+/** The system calls that resolve the host's name and open the connection. */
+const CONNECTION_SETUP_CALLS = new Set(["getaddrinfo", "connect"]);
+/**
+ * The codes only a step of the connection's set-up gives: the name lookup's and the connect call's
+ * own (set even where Node reports several addresses together, without a system call), undici's
+ * connect time limit, Node's limit on one attempt among several addresses, Node's own check of the
+ * host's name, and every code Node gives a server certificate the TLS handshake refused.
+ */
+const CONNECTION_SETUP_CODES = new Set([
+    "ECONNREFUSED",
+    "ENOTFOUND",
+    "EAI_AGAIN",
+    "UND_ERR_CONNECT_TIMEOUT",
+    "ERR_SOCKET_CONNECTION_TIMEOUT",
+    "ERR_TLS_CERT_ALTNAME_INVALID",
+    "ERR_TLS_CERT_ALTNAME_FORMAT",
+    // Node names the verdicts of OpenSSL's certificate check from a fixed table, the "X509 certificate
+    // error codes" of its `tls` docs, and gives every other verdict, such as an unhandled critical
+    // extension or a CA certificate that may not sign certificates, the code `UNSPECIFIED`. The
+    // error carries nothing else that marks it, so these codes are the mark: the table as Node 24
+    // compiles it, in its order, then its default. The Python command reads every
+    // `ssl.SSLCertVerificationError` the same way.
+    "UNABLE_TO_GET_ISSUER_CERT",
+    "UNABLE_TO_GET_CRL",
+    "UNABLE_TO_DECRYPT_CERT_SIGNATURE",
+    "UNABLE_TO_DECRYPT_CRL_SIGNATURE",
+    "UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY",
+    "CERT_SIGNATURE_FAILURE",
+    "CRL_SIGNATURE_FAILURE",
+    "CERT_NOT_YET_VALID",
+    "CERT_HAS_EXPIRED",
+    "CRL_NOT_YET_VALID",
+    "CRL_HAS_EXPIRED",
+    "ERROR_IN_CERT_NOT_BEFORE_FIELD",
+    "ERROR_IN_CERT_NOT_AFTER_FIELD",
+    "ERROR_IN_CRL_LAST_UPDATE_FIELD",
+    "ERROR_IN_CRL_NEXT_UPDATE_FIELD",
+    "OUT_OF_MEM",
+    "DEPTH_ZERO_SELF_SIGNED_CERT",
+    "SELF_SIGNED_CERT_IN_CHAIN",
+    "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
+    "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+    "CERT_CHAIN_TOO_LONG",
+    "CERT_REVOKED",
+    "INVALID_CA",
+    "PATH_LENGTH_EXCEEDED",
+    "INVALID_PURPOSE",
+    "CERT_UNTRUSTED",
+    "CERT_REJECTED",
+    "HOSTNAME_MISMATCH",
+    "UNSPECIFIED",
+]);
+/**
+ * Whether a failure met once a request that may create a run was sent, and before the API named
+ * the run, leaves it unknown whether one was created: its answer was lost to a time limit, a
+ * connection that closed once the request had left or a gateway that cut the request off, or it
+ * came back unreadable, or a gateway answered that it lost or never got the server's answer
+ * (`502`, `504`, RFC 9110). A gateway cuts a request off at ~30 seconds, whether a blocking
+ * execute or a start the server is still handling, such as one fetching a `method_ref`'s package:
+ * the SDK's `isGatewayCutOff` tells it, past its threshold, from the time since `onStarting`. Any
+ * other answer from the API, a `503` that came back before that saying the request was not handled
+ * included, and a failure that proves nothing was sent, say no run was created.
+ */
+function mayHaveStarted(stage, error) {
+    if (stage.kind !== "starting")
+        return false;
+    if (error instanceof PipelineExecuteTimeoutError)
+        return true;
+    if (error instanceof ApiUnreachableError)
+        return !provesNothingSent(error);
+    if (!(error instanceof ApiResponseError))
+        return false;
+    if (error.status >= 200 && error.status < 300)
+        return true;
+    return (GATEWAY_LOST_ANSWER.has(error.status) || isGatewayCutOff(error, performance.now() - stage.since));
+}
+/** The gateway statuses that say the server's answer was lost or never came (RFC 9110). */
+const GATEWAY_LOST_ANSWER = new Set([502, 504]);
+/** The line under a failure that leaves it unknown whether a run was created. */
+export 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 function runStillGoingLine(runId) {
+    return `Run ${runId} may still be going on the server, so do not start it again.`;
+}
+/** The method `--method` names, a path being read from disk. */
+async function methodSource(method) {
+    const selector = classifyMethod(method);
+    switch (selector.kind) {
+        case "address":
+            return { kind: "address", methodRef: selector.methodRef };
+        case "catalog":
+            return { kind: "catalog", methodId: selector.methodId };
+        case "path":
+            return { kind: "bundle", files: await readBundle(selector.path) };
+    }
+}
+/**
+ * Upload the local files the inputs name at the method's file inputs, through the SDK's input
+ * preparation, and report each upload on stderr. Inputs that are absent or empty are sent as they
+ * are, with no request: there is nothing to upload.
+ */
+async function prepare(client, source, pipe, inputs, io) {
+    if (inputs === undefined || Object.keys(inputs).length === 0)
+        return inputs;
+    const prepared = await untilInterrupted(() => client.prepareInputs({
+        ...crateSelector(source),
+        ...(pipe === undefined ? {} : { pipe_ref: pipe }),
+        inputs,
+        // Once interrupted, no upload starts after the pipe I/O answer arrives.
+        signal: io.interrupt,
+    }), io.interrupt);
+    for (const upload of prepared.uploads) {
+        io.writeStderr(`Uploaded ${upload.filename} as ${upload.uri}\n`);
+    }
+    return prepared.inputs;
+}
+/** What an interrupt says, by where the run stood. */
+function interruptMessage(stage, templateOnly) {
+    if (templateOnly)
+        return "Interrupted.";
+    switch (stage.kind) {
+        case "local":
+            return "Interrupted. No run was started.";
+        case "starting":
+            return "Interrupted before the API answered with a run id. A run may or may not have started on the server.";
+        case "started":
+            return `Interrupted. Run ${stage.runId} keeps going on the server.`;
+    }
+}
+//# sourceMappingURL=run.js.map

package/dist/cli/run.js.map

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

package/dist/cli/script.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `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 type { CommandIO } from "./io.js";
+/** The package a written script runs, and what its runner needs. */
+export declare const SCRIPT_RUNNER = "npx --yes @pipelex/sdk@0.34.0";
+export declare const SCRIPT_WRITER = "@pipelex/sdk";
+export declare const SCRIPT_NEEDS = "Node 22.12 or later";
+/** Run `pipelex-sdk script` and return its exit code. */
+export declare function runCommandScript(args: readonly string[], io: CommandIO): Promise<number>;
+/**
+ * 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 declare function scriptBody(name: string, method: string, pipe: string | undefined): string;

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":"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"}

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>;