@pipelex/sdk 0.33.0 → 0.34.0

package/README.md

@@ -18,6 +18,24 @@ It also exports `summarizeUsage`, which folds a completed run's usage records in
 npm install @pipelex/sdk
 ```
 
+## Run a method from the command line
+
+The package publishes one command, `pipelex-sdk`, so a method runs with nothing installed but Node 22.12 or later and a key in `PIPELEX_API_KEY`:
+
+```bash
+npx @pipelex/sdk run --method github.com/acme/methods/receipt-review@v1.0.0 --inputs-template > inputs.json
+npx @pipelex/sdk run --method github.com/acme/methods/receipt-review@v1.0.0 --inputs inputs.json
+```
+
+`--method` takes a published address, a catalog id (`mt_…`) or a local `.mthds` file or bundle directory. The run's main output is printed on stdout as JSON, and the run id, each uploaded file and every error on stderr. `script` writes a method its own command, a shell script pinned to this SDK's version:
+
+```bash
+npx @pipelex/sdk script --method github.com/acme/methods/receipt-review@v1.0.0
+./receipt-review --inputs inputs.json
+```
+
+See [`docs/cli.md`](./docs/cli.md) for every flag, the output, the exit codes and Ctrl-C.
+
 ## Usage
 
 ```ts
@@ -114,7 +132,7 @@ try {
 
 ### Client identification
 
-Every request to the API carries a `User-Agent` such as `pipelex-sdk-js/0.21.0 node/22.4.0 (darwin; arm64)`, which the hosted platform reads to attribute traffic to a client surface in its analytics. A program built on the SDK can put its own name in front with `appInfo`, shaped like Stripe's option of that name; an invalid field is refused at construction with a `TypeError`. In a browser the SDK sets no `User-Agent`. A program that also calls the API with its own `fetch` gets the same value from the exported `buildUserAgent(appInfo)`. The convention is the workspace spec `docs/specs/client-identification.md`, and [`docs/client-identification.md`](./docs/client-identification.md) describes this SDK's side of it.
+Every request to the API carries a `User-Agent` such as `pipelex-sdk-js/0.21.0 node/22.4.0 (darwin; arm64)`, which the hosted platform reads to attribute traffic to a client surface in its analytics. A program built on the SDK can put its own name in front with `appInfo`, shaped like Stripe's option of that name; an invalid field is refused at construction with a `TypeError`. In a browser the SDK sets no `User-Agent`. A program that also calls the API with its own `fetch` gets the same value from the exported `buildUserAgent(appInfo)`. The convention is the spec `conformance/specs/client-identification.md`, in the `conformance` repository, where the cross-repo specs sit beside the tests that verify them, and [`docs/client-identification.md`](./docs/client-identification.md) describes this SDK's side of it.
 
 ```ts
 const client = new PipelexApiClient({ appInfo: { name: "acme-invoicer", version: "1.4.0" } });
@@ -147,6 +165,7 @@ These pages ship inside the published package, so a reader who has only installe
 | Page | What it covers |
 | --- | --- |
 | [`docs/architecture.md`](./docs/architecture.md) | The whole client surface: the request pipeline, every route, the typed errors |
+| [`docs/cli.md`](./docs/cli.md) | The `pipelex-sdk` command: `run` and `script`, the environment it reads, what it prints, its exit codes, how it reads a bundle, and the case table it shares with the Python SDK |
 | [`docs/run-results.md`](./docs/run-results.md) | Every field of `RunResults` — the run id as a durable handle, `main_stuff`, `working_memory`, `graph_spec`, the usage pair, produced files |
 | [`docs/run-usage.md`](./docs/run-usage.md) | What a run consumed, record by record, and `summarizeUsage` which folds them into one reading |
 | [`docs/artifact-download.md`](./docs/artifact-download.md) | Turning the `pipelex-storage://` references a run produced back into bytes: `locateArtifacts`, `collectArtifacts`, `resolveArtifacts`, `fetchArtifact`, `downloadArtifacts`, and how a saved file is named after the field it fills |

package/dist/cli/args.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The flags of one subcommand, read with `node:util`'s `parseArgs` and held to rules the Python
+ * twin's `argparse` can follow word for word, so both commands refuse the same command lines.
+ *
+ * `parseArgs` runs in its lenient mode and returns its tokens, and the rules are applied to the
+ * tokens in command-line order, the first problem being the one reported:
+ *
+ * - `--help` or `-h` anywhere before `--` asks for the subcommand's help, whatever else is there,
+ *   even where a flag's value would be expected: an argument that is exactly one of the two is
+ *   never taken as a value, so `run --method --help` prints the help. A parser that would take it
+ *   as the value, as `parseArgs` and `argparse` both do, is followed by a scan for it. The `--`
+ *   that bounds the scan is the one the parser reads as the end of the options, not a `--` a
+ *   string flag took as its value.
+ * - An option the subcommand does not take is refused, and so is any positional argument.
+ * - A flag given twice is refused, rather than the last one winning: a script written by
+ *   `script` passes its own arguments through, and a second `--method` must not quietly run
+ *   another method.
+ * - A string flag needs a non-empty value, given as the next argument or after `=`. A next
+ *   argument that starts with `-` is not taken as the value, except `-` alone, which `--inputs`
+ *   reads as stdin; `--name=-x` is how a value starting with `-` is given.
+ * - A boolean flag takes no value.
+ */
+/** One flag a subcommand takes, by its long name. */
+export interface FlagSpec {
+    readonly type: "string" | "boolean";
+}
+/** The flags a subcommand takes, by long name, without the `--`. */
+export type FlagSpecs = Readonly<Record<string, FlagSpec>>;
+/** What a subcommand's command line asked for. */
+export interface ParsedFlags {
+    /** Whether `--help` was asked for, in which case nothing else was read. */
+    readonly help: boolean;
+    readonly strings: ReadonlyMap<string, string>;
+    readonly booleans: ReadonlySet<string>;
+}
+/**
+ * Read a subcommand's command line against its flags.
+ *
+ * @throws {CommandError} A usage error naming the first problem, in command-line order.
+ */
+export declare function parseFlags(command: string, args: readonly string[], specs: FlagSpecs): ParsedFlags;

package/dist/cli/args.js

@@ -0,0 +1,96 @@
+/**
+ * The flags of one subcommand, read with `node:util`'s `parseArgs` and held to rules the Python
+ * twin's `argparse` can follow word for word, so both commands refuse the same command lines.
+ *
+ * `parseArgs` runs in its lenient mode and returns its tokens, and the rules are applied to the
+ * tokens in command-line order, the first problem being the one reported:
+ *
+ * - `--help` or `-h` anywhere before `--` asks for the subcommand's help, whatever else is there,
+ *   even where a flag's value would be expected: an argument that is exactly one of the two is
+ *   never taken as a value, so `run --method --help` prints the help. A parser that would take it
+ *   as the value, as `parseArgs` and `argparse` both do, is followed by a scan for it. The `--`
+ *   that bounds the scan is the one the parser reads as the end of the options, not a `--` a
+ *   string flag took as its value.
+ * - An option the subcommand does not take is refused, and so is any positional argument.
+ * - A flag given twice is refused, rather than the last one winning: a script written by
+ *   `script` passes its own arguments through, and a second `--method` must not quietly run
+ *   another method.
+ * - A string flag needs a non-empty value, given as the next argument or after `=`. A next
+ *   argument that starts with `-` is not taken as the value, except `-` alone, which `--inputs`
+ *   reads as stdin; `--name=-x` is how a value starting with `-` is given.
+ * - A boolean flag takes no value.
+ */
+import { parseArgs } from "node:util";
+import { usageError } from "./io.js";
+/** The two arguments that ask for a subcommand's help. */
+const HELP_ARGUMENTS = ["--help", "-h"];
+/**
+ * Read a subcommand's command line against its flags.
+ *
+ * @throws {CommandError} A usage error naming the first problem, in command-line order.
+ */
+export function parseFlags(command, args, specs) {
+    const options = {
+        help: { type: "boolean", short: "h" },
+    };
+    for (const [name, spec] of Object.entries(specs))
+        options[name] = { type: spec.type };
+    const { tokens } = parseArgs({
+        args: [...args],
+        options,
+        strict: false,
+        allowPositionals: true,
+        tokens: true,
+    });
+    // The `--` that ends the options is the one the parser reads as such: a `--` a string flag took
+    // as its value ends nothing, so `run --pipe -- --method --help` asks for the help.
+    const terminator = tokens.find((token) => token.kind === "option-terminator");
+    const beforeTerminator = terminator === undefined ? args : args.slice(0, terminator.index);
+    if (beforeTerminator.some((arg) => HELP_ARGUMENTS.includes(arg))) {
+        return { help: true, strings: new Map(), booleans: new Set() };
+    }
+    // `-h` inside a group of short options, such as `-xh`, asks for the help too.
+    if (tokens.some((token) => token.kind === "option" && token.name === "help" && token.value === undefined)) {
+        return { help: true, strings: new Map(), booleans: new Set() };
+    }
+    const strings = new Map();
+    const booleans = new Set();
+    const seen = new Set();
+    for (const token of tokens) {
+        if (token.kind === "option-terminator")
+            continue;
+        if (token.kind === "positional") {
+            throw misuse(command, `unexpected argument "${token.value}"`);
+        }
+        if (token.name === "help")
+            throw misuse(command, "--help takes no value");
+        const spec = Object.hasOwn(specs, token.name) ? specs[token.name] : undefined;
+        if (spec === undefined) {
+            throw misuse(command, `unknown option ${token.rawName}`);
+        }
+        const flag = `--${token.name}`;
+        if (seen.has(token.name)) {
+            throw misuse(command, `${flag} was given more than once`);
+        }
+        seen.add(token.name);
+        if (spec.type === "boolean") {
+            if (token.value !== undefined)
+                throw misuse(command, `${flag} takes no value`);
+            booleans.add(token.name);
+            continue;
+        }
+        const value = token.value;
+        const takenFromNext = !token.inlineValue;
+        if (value === undefined ||
+            value === "" ||
+            (takenFromNext && value.startsWith("-") && value !== "-")) {
+            throw misuse(command, `${flag} needs a value`);
+        }
+        strings.set(token.name, value);
+    }
+    return { help: false, strings, booleans };
+}
+function misuse(command, message) {
+    return usageError(`${message}.`, [`Run 'pipelex-sdk ${command} --help' to see its flags.`]);
+}
+//# sourceMappingURL=args.js.map

package/dist/cli/args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.js","sourceRoot":"","sources":["../../src/cli/args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAGrC,0DAA0D;AAC1D,MAAM,cAAc,GAAsB,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;AAkB3D;;;;GAIG;AACH,MAAM,UAAU,UAAU,CACxB,OAAe,EACf,IAAuB,EACvB,KAAgB;IAEhB,MAAM,OAAO,GAAmE;QAC9E,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE;KACtC,CAAC;IACF,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;IACtF,MAAM,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;QAC3B,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;QACf,OAAO;QACP,MAAM,EAAE,KAAK;QACb,gBAAgB,EAAE,IAAI;QACtB,MAAM,EAAE,IAAI;KACb,CAAC,CAAC;IAEH,gGAAgG;IAChG,mFAAmF;IACnF,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,mBAAmB,CAAC,CAAC;IAC9E,MAAM,gBAAgB,GAAG,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC;IAC3F,IAAI,gBAAgB,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,cAAc,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;QACjE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,GAAG,EAAE,EAAE,QAAQ,EAAE,IAAI,GAAG,EAAE,EAAE,CAAC;IACjE,CAAC;IAED,8EAA8E;IAC9E,IACE,MAAM,CAAC,IAAI,CACT,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,CACzF,EACD,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,GAAG,EAAE,EAAE,QAAQ,EAAE,IAAI,GAAG,EAAE,EAAE,CAAC;IACjE,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC1C,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IACnC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,KAAK,CAAC,IAAI,KAAK,mBAAmB;YAAE,SAAS;QACjD,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;YAChC,MAAM,MAAM,CAAC,OAAO,EAAE,wBAAwB,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC;QAChE,CAAC;QACD,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM;YAAE,MAAM,MAAM,CAAC,OAAO,EAAE,uBAAuB,CAAC,CAAC;QAC1E,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC9E,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,MAAM,MAAM,CAAC,OAAO,EAAE,kBAAkB,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QAC3D,CAAC;QACD,MAAM,IAAI,GAAG,KAAK,KAAK,CAAC,IAAI,EAAE,CAAC;QAC/B,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACzB,MAAM,MAAM,CAAC,OAAO,EAAE,GAAG,IAAI,2BAA2B,CAAC,CAAC;QAC5D,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACrB,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC5B,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS;gBAAE,MAAM,MAAM,CAAC,OAAO,EAAE,GAAG,IAAI,iBAAiB,CAAC,CAAC;YAC/E,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACzB,SAAS;QACX,CAAC;QACD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;QAC1B,MAAM,aAAa,GAAG,CAAC,KAAK,CAAC,WAAW,CAAC;QACzC,IACE,KAAK,KAAK,SAAS;YACnB,KAAK,KAAK,EAAE;YACZ,CAAC,aAAa,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,KAAK,GAAG,CAAC,EACzD,CAAC;YACD,MAAM,MAAM,CAAC,OAAO,EAAE,GAAG,IAAI,gBAAgB,CAAC,CAAC;QACjD,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACjC,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;AAC5C,CAAC;AAED,SAAS,MAAM,CAAC,OAAe,EAAE,OAAe;IAC9C,OAAO,UAAU,CAAC,GAAG,OAAO,GAAG,EAAE,CAAC,oBAAoB,OAAO,4BAA4B,CAAC,CAAC,CAAC;AAC9F,CAAC"}

package/dist/cli/bundle.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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.
+ */
+/** The extension of a bundle's files. */
+export declare const BUNDLE_SUFFIX = ".mthds";
+/** One file of a bundle: the name it is sent under, and its text. */
+export interface BundleFile {
+    readonly name: string;
+    readonly content: string;
+}
+/**
+ * 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 declare function readBundle(given: string): Promise<BundleFile[]>;
+/** Compare two strings code point by code point, which is comparing their UTF-8 bytes. */
+export declare function compareCodePoints(left: string, right: string): number;
+/** The system's reason for a failed file operation: its code, else its message. */
+export declare function systemReason(error: unknown): string;

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