@pipelex/sdk 0.33.0 → 0.34.0

package/dist/cli/inputs.js

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

package/dist/cli/inputs.js.map

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

package/dist/cli/io.d.ts

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

package/dist/cli/io.js

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

package/dist/cli/io.js.map

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

package/dist/cli/main.d.ts

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

package/dist/cli/main.js

@@ -0,0 +1,58 @@
+/**
+ * The `pipelex-sdk` command: `run` runs a method and prints its main output, `script` writes the
+ * per-method shell script. `docs/cli.md` describes both, and `tests/fixtures/cli-cases.json`
+ * records what each prints for every case, which the Python twin answers too.
+ *
+ * Nothing in the SDK imports this module or its siblings, and the package entry does not export
+ * them (`.dependency-cruiser.cjs`): the command sits at the top of the dependency graph, and reaches
+ * the SDK only through its public barrel, as any other caller would.
+ */
+import { SDK_VERSION } from "../index.js";
+import { MAIN_HELP } from "./help.js";
+import { EXIT_OK, usageError, writeLines } from "./io.js";
+import { presentError } from "./present.js";
+import { runCommandRun } from "./run.js";
+import { runCommandScript } from "./script.js";
+/**
+ * Run the command on `argv`, the arguments after the command's own name, and return its exit
+ * code: 0 when it did what it was asked, 1 when the run failed or the API refused it, 2 for a
+ * usage error and 130 when interrupted. Every failure is printed on stderr before it returns; it
+ * never throws.
+ */
+export async function runCommand(argv, io) {
+    try {
+        const [command, ...rest] = argv;
+        switch (command) {
+            case undefined:
+                throw usageError("name a command: run or script.", [
+                    "Run 'pipelex-sdk --help' to see what each does.",
+                ]);
+            case "--help":
+            case "-h":
+                // The help wins whatever follows it, as it does in a subcommand.
+                io.writeStdout(MAIN_HELP);
+                return EXIT_OK;
+            case "--version":
+                // Unlike the help, the version is not printed over a command line it does not answer.
+                if (rest.length > 0) {
+                    throw usageError(`unexpected argument "${rest[0]}" after --version.`, [
+                        "Run 'pipelex-sdk --version' alone to print the version.",
+                    ]);
+                }
+                io.writeStdout(`${SDK_VERSION}\n`);
+                return EXIT_OK;
+            case "run":
+                return await runCommandRun(rest, io);
+            case "script":
+                return await runCommandScript(rest, io);
+            default:
+                throw usageError(command.startsWith("-") ? `unknown option ${command}.` : `unknown command "${command}".`, ["The commands are run and script. Run 'pipelex-sdk --help' to see what each does."]);
+        }
+    }
+    catch (error) {
+        const presented = presentError(error);
+        writeLines(io, presented.lines);
+        return presented.exitCode;
+    }
+}
+//# sourceMappingURL=main.js.map

package/dist/cli/main.js.map

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

package/dist/cli/method.d.ts

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

package/dist/cli/method.js

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

package/dist/cli/method.js.map

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

package/dist/cli/present.d.ts

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